5.7 KiB

Raw Blame History

Developing Neutrino

Developing and contributing to Neutrino, its core presets, and middleware is done through our monorepo located at https://github.com/mozilla-neutrino/neutrino-dev. The code is broken up into a couple different sections: packages and documentation.

Note: In this guide, commands executable from the command line are prepended with ❯. Lines not starting with this symbol show sample console output from running the previous command.

Requirements

Developing for neutrino-dev requires:

Node.js v6.9+
Yarn client, installation instructions at https://yarnpkg.com/en/docs/install
git, GitHub account

Getting started

The first step to start developing neutrino-dev is forking the repository to your own GitHub account.

Fork mozilla-neutrino/neutrino-dev on GitHub

Once that is done, you can clone your copy of the repository on your computer, replacing USER with the username of the account you forked the repository to:

❯ git clone git@github.com:USER/neutrino-dev.git
❯ cd neutrino-dev

Upon cloning, you should install dependencies and bootstrap the project:

❯ yarn
❯ yarn bootstrap

This will create symlinks between the various packages, making local development much easier. It also creates yarn links for testing out these packages elsewhere on your system.

Development commands

The package.json for neutrino-dev defines several commands to assist in the development and deployment process.

bootstrap

Installs all sub-package dependencies using yarn. External dependencies are installed normally, whereas those belonging to the neutrino-dev monorepo itself are yarn linked.

❯ yarn bootstrap

changelog

Generates a changelog for the mozilla-neutrino/neutrino-dev GitHub repository. This changelog is output to a CHANGELOG.md file in the root of the repository.

❯ yarn changelog

deps:add [--dev] <package> <...dependencies>

Adds one or more new dependencies or development dependencies to a sub-package. Any flags used, such as --dev are passed on to yarn add. For example, if you wanted to add "lodash.clonedeep" to the neutrino package:

❯ yarn deps:add neutrino lodash.clonedeep

deps:remove <package> <...dependencies>

Removes one or more dependencies from a sub-package. Any flags used are passed on to yarn remove. For example, if you wanted to remove "lodash.clonedeep" from the neutrino package:

❯ yarn deps:remove neutrino lodash.clonedeep

deps:upgrade <package> <...dependencies>

Upgrades one or more dependencies in a sub-package. Any flags used are passed on to yarn upgrade. For example, if you wanted to upgrade "lodash.clonedeep" in the neutrino package:

❯ yarn deps:upgrade neutrino lodash.clonedeep

deps:clean

Removes the node_modules directory from all sub-packages. After running this you will need to re-bootstrap neutrino-dev in order to continue development. Useful if you have somehow put your local development environment in an unworkable state with regards to local inter-dependencies.

❯ yarn deps:clean

docs:serve

Starts a local development server which builds the documentation in docs to a gitbook running on port 4000.

❯ yarn docs:serve

docs:build

Generates a static site by building the documentation in docs to a gitbook to the _book directory.

❯ yarn docs:build

docs:deploy

Generates a static site by building the documentation in docs to a gitbook to the _book directory, then pushing the contents of _book to a gh-pages branch on GitHub. In order to run this command, you must have an upstream remote configured pointing to the root neutrino-dev repo, and have sufficient rights to push to the repository.

❯ yarn docs:deploy

Making changes

When you make changes to neutrino-dev, you should make them in a branch separate from master. Start from the master branch and create a new branch for your changes.

Example: You want to create a core preset for JavaScript Standard Style. You need a new branch for this work.

❯ git checkout -b standard-style
Switched to a new branch 'standard-style'

While making changes, be sure to test your code out for expected operation. If possible or applicable, write a test that can verify these changes in the future.

Submitting a pull request

Once you are satisfied with your changes, you should commit them and submit a pull request. Use git add in order to add files that should be committed. Give your changes a descriptive but not overly verbose message.

❯ git add .
❯ git commit -m "Feature: Adding new core preset for JavaScript Standard Style"
❯ git push origin standard-style

Now if you open the GitHub page for your repository, GitHub should display a button to open a pull request for the branch and commit you just pushed. When filling out the details of the pull request, try to be as descriptive as possible, following our detailed contribution guidelines.

Congrats!

You just made a contribution to Neutrino! We are so happy to have your help! 🎉

Receiving updates

If you need to update your local copy of neutrino-dev to be in sync with the main neutrino-dev repository, you will want to fetch upstream changes. Add the main neutrino-dev repo as an upstream to your local copy, then fetch the latest changes from the master branch.

❯ git checkout master
❯ git remote add upstream https://github.com/mozilla-neutrino/neutrino-dev.git
❯ git pull upstream master

5.7 KiB Raw Blame History