Table of Contents
Creating an Open Source Library
License, Code of Conduct, & READMEBefore starting an open source project, Kent recommends deciding on an open source license and creating a code of conduct. The license helps outline any restrictions around how the library can be used. While not required, the code of conduct can set behavior expectation for contributors.
Exercise: Creating the Code of Conduct and License.In this exercise, Kent walks through creating the CODE_OF_CONDUCT.md, LICENSE, and README.md files. These files are written with Markdown syntax to make it easy to format them for the web. The solution to this exercise is on the FEM/01.0-important branch.
NPM Configuration and NPM InitThe “npm init” command will initialize a project and create the package.json file. There are a few questions asked by NPM each time the “init” command is run so Kent demonstrates how to update the .npmrc file with pre-populated default values. He then completes the initialization of the star-wars-names project. The code for this example can be found on the FEM/03.0-add-data branch.
Exercise: Creating the LibraryKent sets up the next exercise with a little pseudo code before turning it over to the group. In this exercise you will create the index.js file, install the unique-random-array module, and add the node_modules directory to the .gitignore file.
Creating the Library SolutionKent walks through the solution to the Creating the Library exercise. The code for the solution is located on the FEM/03.1-create-lib branch.
Linting & Testing
ESLintLinting code catches errors, encourages best practices and maintains consistency throughout the project. Kent introduces ESLint and talks about how it compares to JSLint and JSHint. The main advantage of ESLint is that it’s more flexible and pluggable.
Exercise: Linting the LibraryIn this exercise, Kent installs the eslint Node module. He then walks through the configuration and writing of the library’s first lint script. The solution to this exercise is on the FEM/04.0-linting branch.
Exercise: Setting Up Mocha & ChaiMocha and Chai are unit testing and assertion libraries. In this exercise, Kent demonstrates how to get an initial test runner set up in the library. He creates an index.test.js file which will contain the test scripts and a mocha.opts file for configuring Mocha. The solution to this exercise is on the FEM/05.0-setup-tests branch.
Exercise: Writing Unit TestsIn this exercise, you will write unit tests that cover the starWarsNames.all() and starWarsNames.random() methods. To start, Kent provides some pseudo-code and a few hints. He also talks a little about the dont-break NPM package that verifies changes to one project don’t break dependent projects.
Writing Unit Tests SolutionKent walks through the solution to the Writing Unit Tests exercise. The code for the solution is located on the FEM/05.1-write-tests branch.
Code CoverageCode coverage is the process of monitoring how much code is “covered” by a unit test. Code coverage tools can monitor anything from statements and lines to functions and branches. Target thresholds are set in the configuration and coverage reports are output to the command line.
Configuring NYCKent spends some time demonstrating how to install and configure the nyc Node module to run test coverage reports in the library. After establishing the reports, Kent adds lcov reports which are browser-based and more descriptive. The code for this example is on the FEM/05.2-coverage branch.
Git Hooks, Babel, & Webpack
Git HooksGit Hooks are scripts that run either before or after common Git tasks are performed. For example, a script could be configured to run before a project commit. Git Hooks are separate from other project files so in order to share them between projects, Kent introduces the ghooks Node module which makes sharing possible.
Exercise: Creating a Validate ScriptIn this exercise, Kent walks through how to create a validate script to automatically run the test and linting scripts for the project. The code for this exercise is on the FEM/06.0-validate branch.
TranspilingTranspiling is the process of converting code from one format to another. In the case of this library, Kent will be transpiling from ES6 syntax to ES5 syntax which has more compatibility. To do this, he will be using the Babel transpiler.
Installing & Configuring BabelKent installs and begins configuring Babel. All the transpiled output will be placed in a “dist” directory. After getting some initial configuration in place, Kent demonstrates the transpiling process and talks about a few of Babel’s features.
Sending the Distribution to NPMThe npm pack command creates a zipped bundle of the distribution files as well as some of the other project files. This bundle could then be uploaded to the NPM directory for distribution. After creating this bundle, Kent explores the contents and spends some time configuring the packager so only the necessary files are included.
Babel Register & IstanbulNow that the library is using ES6 syntax and transpiling with Babel, the test scripts will not run. Kent explains why this is happening and introduces the Babel Register plugin which will help alleviate the problem. He also talks about why the Babel plugin, Istanbul will now be used for code coverage.
Exercise: Adding Babel Register & IstanbulIn this exercise, Kent adds babel-register and babel-plugin-istanbul to the project. After configuring these to modules, he uses the NODE_ENV to indicate which environment is being used for each script so the correct plugins will be loaded. Since the NODE_ENV variable only works on OSX, Kent adds the cross-env module which allows it to be set cross platform. The solution to this exercise is on the FEM/07.1-transpile-tests branch.
Adding & Configuring WebpackKent walks through how to add Webpack along with the Babel and JSON loaders. He then creates the build scripts necessary for building the application with Babel and building the UMD version of the library. All the build scripts are joined with an “npm-run-all” script that will execute them in parallel. The code for this example is on the FEM/08.0-browser-build branch.
Peer DependenciesIn response to an audience question, Kent spends a few minutes talking about peer dependencies. When a library uses peer dependencies, it will specify a range of compatible versions. If one of those versions is already available, it will be used instead of a new version getting imported.
Forking & RenamingFor the remainder of the workshop, Kent will be working from a forked version of the Star Wars Names library. After forking the library, he gives it a new name. Because the name is now different, Kent has to spend a few minutes updating all the places “star-wars-names” was used throughout the source code.
Moving to the Master BranchKent unintentionally forked the Star Wars Names library on the wrong branch. To fix this, he leads the group through moving their projects back to the master branch.
Continuous Integration & Automating Releases
Exercise: Setting up Travis CITravis CI is a continuous integration tool that integrates with Github projects. Kent walks through creating a Travis CI account and connecting it to a Github account. After the account is set up, Kent creates the travis.yml configuration file and explains what each of the properties represent. Code for this exercise can be found on the FEM/09.0-setup-travis branch.
Exercise: Tracking Code Coverage with CodecovWhen a library receives pull requests, code coverage of the contributions should continue to be tracked. Kent installs the codecov Node module which will automatically report coverage using the lcov report. Kent then updates the travis.yml configuration file to run the report on the after_success event. After the reports are run Kent demonstrates how to generate badges for the repository README file. Code for this exercise can be found on the FEM/09.1-report-coverage branch.
Publishing to npmjs.comIn order to publish to NPM, first create an account at npmjs.com . Then the “npm publish” command is used to package and upload the library to the NPM registry. After walking through this process, Kent browses a couple of the recently published libraries. The then spends a couple minutes answering audience questions about security and semantic versioning.
Semantic ReleaseSemantic Release is a Node module that will automate package publishing to NPM. It can detect breaking changes, abort releases with insufficient test coverage, and generate change logs from commit messages. Kent spends a few minutes sharing some use cases for Semantic Release.
Semantic Versioning with NPMBefore adding automation with the semantic-release Node module, Kent manually versions the library from the command line with NPM. He bumps the version with the “npm major” command and then demonstrates a few other features like patching and deprecating.
Exercise: Automating Releases Part 1In this exercise, Kent begins the process of automating releases for the library project. He installs and configures the semantic-release-cli module, explaining each step along the way. He then looks at all the changes the semantic-release-cli module made to the project.
Exercise: Automating Releases Part 2Kent continues the exercise which adds automated releases to the project. After looking at a few additional configuration options, Kent spends some time talking about commit message formats. Using a consistent message format makes for more clear and understandable change logs. Code for this exercise can be found on the FEM/09.2-auto-release branch.
Exercise: Using CommitizenIn this exercise, Kent installs the commitizen, cz-conventional-changelog, and validate-commit-msg Node modules. These modules will not only streamline the authoring of commit messages and change logs, but validate the commit messages are formatted properly. Code for this exercise can be found on the FEM/09.3-commit-message branch.
Browsing the Updated LibraryWhile waiting for the library to publish, Kent answers a few questions about publishing and security. Once the library is published he navigates to npmjs.com and views the latest version of the library as well as the change log.
The Open Source Community: Getting StartedKent shares some slides from a previous presentation he gave about participating in the open source community. He revisits a few of the topics from earlier in the workshop about scoping the project, having a code of conduct, and stresses the importance of automation in the workflow.
The Open Source Community: Documentation & IssuesKent continues his discussion about the open source community by sharing his recommendations for creating documentation. He suggests using third-party sites like jsbin.com for providing code examples and explains how to use some Github-provided templates for managing issues.
The Open Source Community: Getting ContributorsContributors are the key to any open source project. Kent concludes his discussion on the open source community by explaining the contributor pipeline. He also shares some advice for encouraging newcomers and those with less open source experience to contribute to projects.
ResourcesKent wraps up his workshop by sharing a number of resources about managing and contributing to open source projects.