Writing good quality software involves several tasks in addition to writing the code. Maintaining a code repository, testing, and writing consistent documentation are some of the tasks that need to be done when working with other people. This is also the case when we write charts and visualizations with D3. If we create a charting package, we would like to make it easy for others to use it and integrate it in their projects. In this chapter, we will describe a workflow and the tools that will help us to create a charting package. In this chapter, we will cover the following tasks:
- Creating a repository: A version control system should be used. In some cases, this involves configuring a central repository.
- Designing the API: Decide how to organize the code in logic units and how the package functionality will be exposed.
- Writing the code: Implement the package components and features.
- Testing: The package components should be tested to minimize the risk of introducing unexpected behavior and breaking the existing functionality.
- Building: The source code isn't shipped as is to build a package. This implies that at least source files need to be concatenated and a minified version of the distributable files should be created.
- Hosting the package: The package should be accessible for others to use, even if it's intended for internal usage.
Also, there are a number of conventions and norms about how these tasks should be performed. There may be protocols for the following:
- Committing changes: This is a workflow to know how to merge hot fixes or new features for the next release or the development version of the project. This may include tasks to be done before you push for changes, such as testing the code or having code review sessions.
- Creating a release: This is a procedure to create, tag, and release new versions of the software, including how to follow a system to tag releases with version numbers.
- Writing code: This is a set of coding practices and conventions agreed upon by the teams.
Most of these tasks and protocols depend on the team and the type of project, but it is almost certain that a number of them will (or should) be in place.
In this chapter, we will create a D3-based charting package. We will use tools to check code conventions, test, and build distributable files for our charting package. Even if the tools that we will use have proven to be successful and are widely used in frontend projects, you may prefer to use different tools for some of the tasks. Feel free to explore and discover a toolset more appropriate for your workflow.
In this section, we will provide an overview of the workflow to create and distribute our charting package. We will also discuss some conventions regarding version numbers and the process of creating a release, introduce tools that will help us to manage the dependences with other projects, run the tests, and automate the package building process.
We begin by creating the project directory and the initial package content. During the development of our charting package, we need to perform the following actions:
- Implement new features or modify the existing code
- Check whether our code follows the coding guidelines
- Implement tests for the new functionality or create additional tests for the existing features
- Run tests to ensure that the modifications don't introduce unexpected behaviors or break the public API
- Concatenate the source files to generate a single JavaScript file that contains the charting package
- Generate a minified file
When implementing new features or fixing bugs, we will modify the code, check for errors, and run the tests. We will repeat the modify-check-test cycle several times until we finish implementing the feature or fix the bug. At this point, we will check and test the code again, build the package, and commit our changes.
As mentioned before, there are many tools that will help us to automate these tasks. There are a great number of tools to make the frontend workflow easier, and every developer has his or her preferences and opinions in this regard. In this chapter, we will use Node.js modules to orchestrate our development tasks. We will use the following tools:
- Vows: This is an asynchronous, behavior-driven JavaScript testing framework for Node.js. We will use Vows to test our charting package.
- Grunt: This is a task runner for Node.js. We will use Grunt and some plugins to check the source files, concatenate, minify, and test our package.
- Bower: This is a frontend package management system. We will configure our package such that users can install our package and its dependencies (D3) easily.
Depending on our development workflow, we may want to create a release. A release is a state of our package that we distribute for it to be used. It's usually identified with a version number that indicates how much it has changed from the previous versions.
The version number is especially important in systems with many dependencies. Depending too much on the functionality provided by a specific version of a package can lead to a version lock, that is, the inability to update the package without having to release new versions of our own package. On the other hand, if we update the package assuming that it's compatible with our software, we will eventually find that it is not the case and that the package has made changes to the API that are not compatible with our software.
Semantic Versioning is a useful convention that helps you to know if it's safe to update a package, as long as it follows the Semantic Versioning convention. The complete specification of Semantic Versioning 2.0.0 (yes, the specification itself is versioned) is available at http://semver.org/. The key points of the Semantic Versioning convention are as follows.
Each release should be assigned a version number of the form MAJOR.MINOR.PATCH, with optional identifiers after a dash (1.0.0-beta, for instance). The version numbers are integers (without leading zeros) and should be incremented when we create a new release by the following rules:
When we increment the MAJOR version, MINOR and PATCH are set to zero; increments in MINOR will reset the PATCH number to zero. The content of a release must not be modified; any modification should be released as a new version.
If we follow this convention, users will know that upgrading from 2.1.34 to 2.1.38 is safe and upgrading from 2.1.38 to 2.2.0 is also safe (and it may provide additional backward-compatible features), while upgrading from 2.2.0 to 3.0.1 will require you to check whether the changes in the new version are still compatible with the existing code. In the next sections, we will create the initial content of the package and configure the tools to test and build our package.