Evaluating Packages Part 2 - Review repository

NAVIGATION

Is it clear how to use the package

Why was the package created

Is it maintained

Is the scope clear

Do people complain or try to fix it

Can you read the code

At this point you know

You are trying to choose between packages with similar functionality. Now you know how to quickly look at project statistics and leverage the legwork done by the community. At this point, you have narrowed down to only a few candidates. Let's look at ways to deepen the level of understanding of what shape a project is in by reviewing the project repository.

comparison

We will continue to investigate the right choice of package for coloring terminal output. Our candidates are chalk and colors.

Is it clear how to use the package

Start by looking at the project home page. For many modules, this is simply a Github README file. Does it provide a clear explanation of how the package is used? Does it have an introductory example of the most basic use case? Do you understand it?

For example, the front page for the yargs package sings in a piratey tune that is fun, but as a user of that package, it is sometimes hard to see the information from the swash-buckling theme.

Both chalk and colors provide a clear explanation of how to use the package. Chalk leaves a slightly better taste with its top-down approach presenting things in the order the reader is interested. This might hint of good taste and user-friendliness down the line.

Why was the package created

A popular package is aware of its friendly competition. Sometimes a new package is deliberately created in order to work around a specific problem or to introduce new design philosophy. This is often stated in the project home page.

Chalk was partly created because colors extended directly String.prototype, which is not considered good design. This is good information and aligns with the world view of the reader.

Is it maintained

Take a look at releases and commits. When was the last commit or release made? Has there been a lot of them lately, or has the active development phase passed?

A trivial or even small package is possible to right at the first attempt and then just leave it be. But if the package is any larger, it is quite certain there has to be improvements and enhancements to make it worthwhile for others to use. Any sign that a package is sliding towards unmaintained state is a red flag.

At some point, even well-maintained project saturates and reaches a peaceful state with not much influx of new issues. But even then, transitive dependencies should be updated once in a while to make the package work nicely with projects built today. Try to see which is the case.

Chalk is active commit-wise and has few recent releases, with some of the changes related to non-functional parts. This can be read as the project has saturated and has time to update the web site and such. Colors has a slightly lower commit activity but has frequently put out a release two times a year. Both seem to be at a mature and maintained good state.

Is the scope clear

Is the scope of the package clear and well defined? Does it try to do too much? Does it adhere to the "do one thing well" principle that well suits npm packages?

Having a behemoth of scope for a project is an easy way to get a lot of maintenance burden on the shoulders of the module authors. No matter how well you try to keep up with bug fixes, there's always the risk of getting behind. Some parts of the big project are going to get less attention and leaves room for bugs to creep in.

Both chalk and colors solve a clearly defined and sufficiently small problem: translate ASCII color codes, such as "ESC]10;", to human-readable colors. This is a perfect example of a clearly scoped package.

Do people complain or try to fix it

Does the project have many outstanding issues? Is any of them been hanging for a while and gathered a ton of comments? This could be a warning sign unless the issues are explorations of new features.

You might also want to check forks, pull requests, and closed issues. A fork indicates that someone is not happy with the project and decides to modify it, but it is also part of the process of creating pull requests. In turn, a number of forks also indicate a willingness to improve the project. This should be in level with the number of closed issues and accepted pull requests.

Chalk has practically zero issues, and all pull requests are closed. Colors has quite a few open issues, some of them have been open for a while. Both projects have a small amount of forks.

Can you read the code

What if the package would need some tweaking. Could you fix it yourself? For this, a quick read of the source code is in place. You can start with the main entry point of the package and go from there to a couple of referenced files.

Both projects have a fairly small source codebase, and both seem to use white-space rich, clear coding style. Both projects are well readable.

At this point you know

At this point, you start to get a feeling of what direction you need to be going. First, turn to the community for their collective opinion in the form of stars, downloads, and other metrics. Then, review the last candidates yourself, and you are in a good situation for decision making.

Based on both community evaluation and repository review, the preferred package for terminal colors is chalk.

Related articles

Semantic Versioning Cheatsheet

Semantic Versioning Cheatsheet

Learn the difference between caret (^) and tilde (~) in package.json.

Get Cheatsheet

Loading Comments