The very latest version of this file can always be found in the template repository.
This library uses the Gitflow model for managing branches in our Git repository:
Branch | Purpose |
---|---|
master |
latest tagged release |
develop |
completed features and fixes waiting for final testing and release |
feature/XXX |
work in progress, to be merged into develop when completed |
release/XXX |
a release that is undergoing final testing, to be merged into master and develop when completed |
hotfix/XXX |
emergency bug fixes in progress, to be merged into master and released when completed |
- Create a new feature branch for each bug fix or new feature.
- Always merge from
develop
into your feature branch right before you create your pull request. - Create a pull request before merging each feature branch into
develop
. - Assign the pull request to a milestone in GitHub.
- Always delete the feature branch once the pull request is accepted.
- Never commit directly to
master
.
Gitflow makes it easy for multiple people to work on the same code base at the same time. It isolates work-in-progress, and provides a single source of truth for accepted-work.
It also provides a clear history / audit trail through the list of merged pull requests.
This library uses jasmine
for unit tests, and nyc
/ Istanbul for code coverage metrics. See the README for instructions on how to run these.
- We picked
jasmine
because the Angular community use it, and because the resulting unit tests are very easy to read.
- All code merged into the
develop
branch must have (at least) 100% code coverage. - Hotfixes (by their nature) are emergency releases. Emergency releases are normally time-sensitive. You must try to get 100% code coverage if time allows. If you can't, you must fill in the missing unit tests after the hotfix has been released.
- 100% code coverage does not guarantee that we're not shipping bugs. Code that isn't covered by unit tests almost certainly does contain bugs.
- Type-safety never removes the need for unit testing.
- It costs more to fix bugs than it does to prevent them.
- Library source code goes into
src/
folder. - The NPM scripts compile the code into the
lib/
folder. - Unit test code goes into the same folder as the code that it tests.
- It's a lot easier to keep the Git repo clean if the compiled code is kept separate from the source code.
- It's a lot easier to find unit tests if the test code is co-located with the code that it tests.
This library uses the multi-variance approach.
- The NPM package contains multiple API versions.
- API source code goes into
src/V1
,src/V2
, etc etc. - Each API version needs a
V1/package.json
,V2/package.json
.
- Shipping multiple API versions in the one package avoids the Great Guzzle Fiasco from the PHP world.
- Top-level
V1/package.json
etc are the only way to hide thelib/
folder fromimport {} from "..."
statements in end-user code.
Every code file in this library must start with the LICENSE comment.
This library uses tslint
to enforce our preferred code layout. See the README for instructions on how to run the linter.
If you use VS Code as your IDE, it should pick up the linting rules automatically.
This library follows semantic versioning.
The guiding principle is that a user should be able to upgrade from v1.0.0
to the latest v1.x.x
release without having to change their own code.
Anything that breaks this promise is a backwards-compatibility break - even if the SemVer website says otherwise.
Any future release may include emergency fixes, such as a security fix. For the good of the Internet, it's important that any user can get those fixes with the least amount of effort possible.
This library also follows the multi-variance approach.
- The NPM package contains all the different, currently-supported API versions.
- The NPM package's major number is the major number of the earliest API that is still supported.
- Unless the package is trivial, the end-user API will end up changing one day.
- Shipping multiple API versions in the same package reduces duplication.
- It also avoids the Great Guzzle Fiasco from the PHP world.