How to open-source a project in 4 steps: Part 2

Authors: Liat Gofshtein, Ori Neuman

Welcome to the second and final installment of our blog series!

In Part 1, we created a GitHub project, created a monorepo using Lerna, added our first package, and connected our project to CI\CD using GitHub Actions.

Part 2 covers the remaining steps for creating your open source project:

1. Publishing
2. Documenting your project

Publishing

You’ll be using npm as your registry to publish your open source project.
npm is a large software registry that contains many packages, including both open source and private developments.

It’s free to use in open source projects, which is great for us!
With npm you can easily push new projects and install all its public projects.

Versioning

Use Semantic Versioning (SEMVER) for versioning in npm.
Each version is made up of 3 numbers that represent the following release type:

MAJOR.MINOR.PATCH.

We recommend that you follow this convention in order to avoid the risk of breaking your software, and to give your users the ability to understand the extent of your changes in each release.

How to publish to npm

Wouldn’t it be nice and simple if you could just run the yarn publish command from the package you want to publish? It would definitely work and your package would be uploaded to npm.

But from that point on, any change you’d make in your package would require you to manually change the version in package.json, add changelogs, release notes and GitHub releases, and eventually run the yarn publish command.

As software developers, we know it’s safer and more efficient to say NO to manual changes and YES to automatic tools that can do the work for us. So, meet Auto. Auto is an automated release tool that generates releases based on semantic version labels on pull requests. Auto is constantly publishing in a CI environment, and does all the important and hard work for you:

• Calculating semantic version bumps from pull requests
• Generating changelogs and release notes
• Making GitHub releases
• Publishing to npm

It performs all these steps using one simple command: auto shipit.

When you run the auto shipit command from a base branch, Auto performs all the steps listed above.

When you run auto shipit from a non-base branch (e.g. PR, locally, etc.), it publishes canary releases.

Here are the relevant configurations for CI environments:

• CircleCI
• Travis CI
• GitHub Actions
• Jenkins 2

Documenting your project

When a user finds your open source, they’ll immediately start looking for information: What is it about? What does it look like? What features were released? How can it be used? The more inviting and informative your documentation, the more people will want to use it.

There are many options and automation tools to document your open source. In React Tree, we use 2 documentation techniques:

• README.md file
• Storybook

README

When accessing an open source’s npm page or GitHub repository, the README file is the first thing that pops up. This is your user’s first impression of your open source project. If it’s empty, too long, or confusing, your user will just look for another solution no matter how great your project might be.

We want your project to achieve the opposite — attract your user’s attention, get them interested, and ultimately get them to choose your open source.

So how do you create an informative and engaging README file? There are no rules set in stone, but here’s a list of things that can help:

• Title: The name of your open source project.
• Introduction: A short description of the project.
• Demo: This can be a gif, an image, or a demo link. This may sound minor but it catches the eye and gives your audience a glimpse of your open source.

For example:

• How to install: You can mention both yarn and npm options.
• How to use: This can be a guide, a code example, or any other type of information that explains how to use your open source.
• Contribute: Let users know how they can contribute to your open source.
• Credits: Give credit to people who contributed, whether it’s a library, contributors, another open source project, etc.
• Technologies: The languages and libraries you used.

In our React Tree open source at Kenshoo, we use two kind of README files:

• Package README file: :Located under a specific package, this file contains all the information about the package such as the title, description, demo, technologies, how to install, how to use, etc. See react-tree readme and material-tree readme.
• Main README file: Located under the root, this file contains general information such as a general description, existing packages (with links to their README files), common APIs, how to contribute, and credits. See main readme.

Storybook

Storybook is a nice, easy-to-manage tool for both developers and the users of your open source. It can be used in React, Vue, Angular, and other frameworks and libraries.

For developers, it allows them to work on their component in its own context while developing. You can work on each component separately in an easy and fast manner. Check out this blog post to learn how Storybook was useful for us.

For open source users, this is the demo! Storybook lets your user experience your open source and see its feature options.

Storybook is made up of stories. A story is a representation of the component you developed. It allows you to capture various rendered states that represent different use cases of your component.

Here’s an example of our React Tree storybook at Kenshoo:

This example shows the 2 different themes that are supported in React Tree. For each theme, you can see all the available options and features, including the default state, using custom renderers, marking selected items, etc.

When a user downloads our open source and runs our storybook, they can easily understand how the components work, what options are available, and how to use each one.

How to install Storybook

Run this command in your project’s root directory:

npx sb init

How to add a story

You can use Storybook’s How to write stories guide, and take a look at React Tree stories examples.

How to run Storybook

Run this command in your project’s root directory:

npm run storybook

This will start Storybook locally.

It might automatically navigate you to the stories webpage, or just output the address that you should navigate to, depends on the configurations.

In conclusion

Creating an open source project requires familiarity with lots of different areas that are not necessarily related to the code itself.

Luckily, thanks to all the open source tools mentioned in this blog series, it’s possible to easily and quickly create your project.

Open source creation is a broad and interesting subject, and we hope this guide will help you start an open source project on your own. So if you’ve made it this far, we can officially say, welcome to the open source community!