- 1. Overview
- 1. Continuous deployment with
semantic-release - 2. Publishing to npm
- 3. Installing archetypes-rules
- 4. Release team
- 5. Release communication
- 6. Process
- 7. Emergency releases
archetypes-rules is a Node.js module
signatures.json.
We use a product manifest file called package.json to describe and publish
archetypes-rules revisions as packages
The development community usually installs Node.js packages with a dependency manager. The two most popular Node.js dependency managers are
- npm
- Yarn
Always install, uninstall, and update modules with a dependency manager.
- Regular releases
- Production-ready modules that designate the types of changes in each release with [semantic versioning][semver-spec].
- Pre-releases
- Preview releases that are not yet considered production-ready.
If your source code cannot be installed (e.g., with a dependency manager), or has no public API, it's not a release candidate!
archetypes-rules uses semantic-release.
Whenever source code is merged into master (after passing all unit tests with
code coverage thresholds satisfied), we automatically:
-
Bump the semantic version of archetypes-rules (based on conventional commits).
-
Update the CHANGELOG.md file.
-
Generate release notes.
-
Publish the archetypes-rules to the public npm registry.
The semantic-release package will publish a new package whenever changes have
been successfully merged into master.
npm run semantic-release
Test semantic-release without really publishing
Open a Terminal and change into your archetypes-rules directory.
Then run:
npm run semantic-release -- --dry-runThe --dry-run option executes semantic-release without actually publishing
anything. You should see output similar to this:
> [email protected] semantic-release /Users/username/Projects/gitlab/archetypes-rules/signatures
> semantic-release "--dry-run"
[8:00:23 PM] [semantic-release] › ℹ Running semantic-release version 15.13.3
[8:00:23 PM] [semantic-release] › ✔ Loaded plugin "verifyConditions" from "@semantic-release/changelog"
[8:00:23 PM] [semantic-release] › ✔ Loaded plugin "verifyConditions" from "@semantic-release/gitlab"
[8:00:23 PM] [semantic-release] › ✔ Loaded plugin "verifyConditions" from "@semantic-release/npm"
[8:00:23 PM] [semantic-release] › ✔ Loaded plugin "analyzeCommits" from "@semantic-release/commit-analyzer"
[8:00:23 PM] [semantic-release] › ✔ Loaded plugin "generateNotes" from "@semantic-release/release-notes-generator"
[8:00:23 PM] [semantic-release] › ✔ Loaded plugin "publish" from "@semantic-release/gitlab"
[8:00:23 PM] [semantic-release] › ✔ Loaded plugin "publish" from "@semantic-release/npm"
[8:00:23 PM] [semantic-release] › ℹ This test run was triggered on the branch 1-api-signatures, while semantic-release is configured to only publish from master, therefore a new version won’t be published.npm install **archetypes-rules** --globalTry to form a team of at least two people to validate every release. This release team—usually a Maintainer (or Trusted Committer) and a Contributor—should oversee every release. This two-person team is responsible for:
- The (scheduled) release
- Monitoring issues over the weekend
- Determining if a patch release is necessary
- Publishing the patch release (if necessary)
The two-person team should seek input from the whole team two business days following a release to double-check if a patch release is necessary.
Each release should have a release issue in Gitlab. The release issue is the source of information for the team about the status of a release. Be sure the release issue has the type: release label so that it's easy to find.
Each product SHOULD use the following communication channels:
- Twitter: every product should have a dedicated Twitter account
- Repository CHANGELOG.md to document the changes made with every release ever made
- Repository README.md edits (for new features or breaking API changes)
- NOTICE.md updates that publically list all product dependencies and their SPDX licenses
- Gitlab Release with the changes made by (semantic) version
- Public artifact registry/repository documentation for each release (e.g., npm, Maven Central)
On the day of a release, the release team should follow these steps:
- Review open Pull Requests to see if any should be merged. In general, you
can merge Pull Requests that:
- Have been open at least two days and have been reviewed (these are just waiting for merge).
- Important Pull Requests (as determined by the team). You should stop and have people review before merging if they haven't been already.
- Documentation changes.
- Small defect fixes written by a team member.
- Squash and merge the branch with changes into
master. - Wait for the "semantic-release" job (in the .gitlab-ci.yml) to complete.
- Update the release blog post with a "Highlights" section, including new rules and anything else that's important.
- Make a release announcement on Twitter.
- Make a release announcement on the release issue. Document any problems that occurred during the release, and remind the team not to merge anything other than documentation changes and defect fixes. Leave the release issue open.
- Add the
patch release pendinglabel to the release issue. (When this label is present,eslint-github-botwill create a pending status check on non-semver-patch Pull Requests, to ensure that they aren't accidentally merged while a patch release is pending.)
Two business days following the (scheduled) release, the release team needs to determine if a patch release is necessary. A patch release is considered necessary if any of the following occurred since the scheduled release:
- A regression defect is causing people's lint builds to fail when it previously passed.
- Any defect that is causing a lot of problems for users (frequently happens due to new functionality).
The patch release decision should be made as early as possible. If a patch release is necessary, then follow the same steps as the scheduled release process.
In rare cases, a second patch release might be necessary if the release is known to have a severe regression that hasn't been fixed by Monday. If this occurs, the release team should announce the situation on the release issue, and leave the issue open until all patch releases are complete. However, it's usually better to fix defects for the next release cycle rather than doing a second patch release.
After the patch release has been published (or no patch release is necessary), close the release issue and inform the team that they can start merging in semver-minor changes again.
In general, we try not to do emergency releases (an emergency release is unplanned and isn't the regularly scheduled release or the anticipated patch release). Even if there is a regression, it's best to wait the weekend to see if any other problems arise so a patch release can fix as many issues as possible.
The only real exception is if archetypes-rules is completely unusable by most of the current users. For instance, we once pushed a release that errored for everyone because it was missing some core files. In that case, an emergency release is appropriate.
