This document describes how to set up your development environment to build and test Template Studio (v2), and
explains the basic mechanics of using git
, node
, npm
.
Before you can build Template Studio (v2), you must install and configure the following dependencies on your machine:
-
Git: The Github Guide to Installing Git is a good source of information.
-
Node.js v10.16.0 'Dubnium' (LTS): We use Node to generate the documentation, run a development web server, run tests, and generate distributable files. Depending on your system, you can install Node either from source or as a pre-packaged bundle.
We recommend using nvm (or nvm-windows) to manage and install Node.js, which makes it easy to change the version of Node.js per project.
To contribute code to Template Studio (v2), you must have a GitHub account so you can push code to your own fork of Template Studio (v2) and open Pull Requests in the GitHub Repository.
To create a Github account, follow the instructions here. Afterwards, go ahead and fork the main Template Studio (v2) repository.
To build Template Studio (v2), you clone the source code repository and use lerna to build:
# Clone your Github repository:
git clone https://github.com/<github username>/template-studio-v2.git
# Go to the Template Studio (v2) directory:
cd template-studio-v2
# Add the main Template Studio (v2) repository as an upstream remote to your repository:
git remote add upstream "https://github.com/accordproject/template-studio-v2.git"
# Install node.js dependencies:
npm install
It is good practice to always keep your origin/master
in sync with upstream/master
. You don’t have to, but it makes your life easier. Do your work in branches of your fork, and periodically sync up your master
with the master
of upstream
as follows. You should definitely do this before creating a pull request.
git fetch --all --prune
git checkout master
git merge --ff-only upstream/master
git push origin master
We write unit and integration tests with Enzyme and execute them with Jest. To run all of the tests once on Chrome run:
npm run test
To ensure consistency throughout the source code, keep these rules in mind as you are working:
- All features or bug fixes must be tested by one or more specs.
- All public API methods must be documented with jsdoc. To see how we document our APIs, please check out the existing source code and see the section about writing documentation
- With the exceptions listed below, we follow the rules contained in Google's JavaScript Style Guide.
We have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history and git logs. But also, we use the git commit messages to generate the Template Studio v2 change log.
The commit message formatting can be added using a version of typical git workflow.
Each commit message consists of a mandatory type, scope, subject, and footer. This is a specific format:
<type>(<scope>): <subject> - <footer>
This allows the message to be easier to read on GitHub as well as in various git tools.
If the commit reverts a previous commit, it should begin with revert:
, followed by the subject, where it
should say: this reverts commit <hash>.
, where the hash is the SHA of the commit being reverted.
A commit with this format is automatically created by the git revert
command.
Must be one of the following:
feat
: A new featurefix
: A bug fixdocs
: Documentation only changesstyle
: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)refactor
: A code change that neither fixes a bug nor adds a featureperf
: A code change that improves performancetest
: Adding missing or correcting existing testschore
: Changes to the build process or auxiliary tools and libraries such as documentation generation
The scope will be specifying the place of the commit change; the focal point of new code or best description of where changes can be found.
You can use *
when the change affects more than a single scope.
The subject contains succinct description of the change:
- use the imperative, present tense: "change" not "changed" nor "changes"
- don't capitalize the first letter
- kept under 50 characters
- no dot (.) at the end
The footer should contain reference GitHub Issues that this commit addresses.
Pull Requests should consist of a complete addition to the code which contains value. Because the commits inside follow a pattern, the title should be an extension or summary of all the commits inside.
Pull Request titles should follow commit message formatting.
Formatting for the body is displayed in this example:
# Issue #20
### Changes
- Change one
- Subchange one
- Subchange two
- Change two
- Theoretically, this should be listing all the commit messages included in this PR
### Flags
- Possible issues or holds for reviewers to note
- List any breaking changes here.
### Related Issues
- Link any issues or pull requests relating to this
When approved and ready to merge, a Pull Request should be squashed down to a single buildable commit and merged into master.
The Template Studio v2 project uses jsdoc for all of its code documentation.
This means that all the docs are stored inline in the source code and so are kept in sync as it changes.
This means that since we generate the documentation from the source code, we can easily provide version-specific documentation by simply checking out a version of Template Studio v2 and running the build.
Accord Project source code files are made available under the Apache License, Version 2.0.
Accord Project documentation files are made available under the Creative Commons Attribution 4.0 International License (CC-BY-4.0).