Maintainers
This is a list of maintainers for this project. See CODEOWNERS.md for list of reviewers for different parts of the codebase. Team members include:
Maintainers:
- @natalialuzuriaga
- @decause-gov
Approvers:
- @natalialuzuriaga
- @decause-gov
Reviewers:
- @IsaacMilarky
- @DinneK
- @sachin-panayil
| Roles |
Responsibilities |
Requirements |
Defined by |
| member |
active contributor in the community |
multiple contributions to the project. |
PROJECT GitHub org Committer Team |
| reviewer |
review contributions from other members |
history of review and authorship in a sub-project |
MAINTAINERS file reviewer entry, and GitHub Org Triage Team |
| approver |
approve accepting contributions |
highly experienced and active reviewer + contributor to a sub-project |
MAINTAINERS file approver entry and GitHub Triage Team |
| lead |
set direction and priorities for a sub-project |
demonstrated responsibility and excellent technical judgement for the sub-project |
MAINTAINERS file owner entry and GitHub Org Admin Team |
Contributors
Total number of contributors:
Natalia Luzuriaga
|
Sachin Panayil
|
decause-gov
|
cms-eo14168
|
</table>
# Tier 3 Release Guidelines
gov-codejson will see regular updates and new releases. This document describes the general guidelines around how and when a new release is cut.
## Table of Contents
- [Versioning](#versioning)
- [Ongoing version support](#ongoing-version-support)
- [Release Process](#release-process)
- [Goals](#goals)
- [Schedule](#schedule)
- [Communication and Workflow](#communication-and-workflow)
- [Preparing a Release Candidate](#preparing-a-release-candidate)
- [Incorporating feedback from review](#incorporating-feedback-from-review)
- [Making a Release](#making-a-release)
- [Auto Changelog](#auto-changelog)
- [Hotfix Releases](#hotfix-releases)
## Versioning
gov-codejson uses [Semantic Versioning](https://semver.org/). Each release is associated with a [`git tag`](github.com/DSACMS/gov-codejson/tags) of the form `X.Y.Z`.
Given a version number in the `MAJOR.MINOR.PATCH` (eg., `X.Y.Z`) format, here are the differences in these terms:
- **MAJOR** version - make breaking/incompatible API changes
- **MINOR** version - add functionality in a backwards compatible manner
- **PATCH** version - make backwards compatible bug fixes
### Ongoing version support
## Release Process
The sections below define the release process itself, including timeline, roles, and communication best practices.
### Goals
.
### Schedule
### Communication and Workflow
## Preparing a Release Candidate
The following steps outline the process to prepare a Release Candidate of gov-codejson. This process makes public the intention and contents of an upcoming release, while allowing work on the next release to continue as usual in `dev`.
1. Create a _Release branch_ from the tip of `dev` named `release-x.y.z`, where `x.y.z` is the intended version of the release. This branch will be used to prepare the Release Candidate. For example, to prepare a Release Candidate for `0.5.0`:
```bash
git fetch
git checkout origin/dev
git checkout -b release-0.5.0
git push -u origin release-0.5.0
```
Changes generated by the steps below should be committed to this branch later.
2. Create a tag like `x.y.z-rcN` for this Release Candidate. For example, for the first `0.5.0` Release Candidate:
```bash
git fetch
git checkout origin/release-0.5.0
git tag 0.5.0-rc1
git push --tags
```
3. Publish a [pre-Release in GitHub](proj-releases-new):
```md
Tag version: [tag you just pushed]
Target: [release branch]
Release title: [X.Y.Z Release Candidate N]
Description: [copy in ReleaseNotes.md created earlier]
This is a pre-release: Check
```
4. Open a Pull Request to `main` from the release branch (eg. `0.5.0-rc1`). This pull request is where review comments and feedback will be collected.
5. Conduct Review of the Pull Request that was opened.
### Incorporating feedback from review
The review process may result in changes being necessary to the release candidate.
For example, if the second Release Candidate for `0.5.0` is being prepared, after committing necessary changes, create a tag on the tip of the release branch like `0.5.0-rc2` and make a new [GitHub pre-Release](proj-releases-new) from there:
```bash
git fetch
git checkout origin/release-0.5.0
# more commits per OMF review
git tag 0.5.0-rc2
git push --tags
```
Repeat as-needed for subsequent Release Candidates. Note the release branch will be pushed to `dev` at key points in the approval process to ensure the community is working with the latest code.
## Making a Release
The following steps describe how to make an approved [Release Candidate](#preparing-a-release-candidate) an official release of gov-codejson:
1. **Approved**. Ensure review has been completed and approval granted.
2. **Main**. Merge the Pull Request created during the Release Candidate process to `main` to make the release official.
3. **Dev**. Open a Pull Request from the release branch to `dev`. Merge this PR to ensure any changes to the Release Candidate during the review process make their way back into `dev`.
4. **Release**. Publish a [Release in GitHub](proj-releases-new) with the following information
- Tag version: [X.Y.Z] (note this will create the tag for the `main` branch code when you publish the release)
- Target: main
- Release title: [X.Y.Z]
- Description: copy in Release Notes created earlier
- This is a pre-release: DO NOT check
5. **Branch**. Finally, keep the release branch and don't delete it. This allows easy access to a browsable spec.
## Auto Changelog
It is recommended to use the provided auto changelog github workflow to populate the project’s CHANGELOG.md file:
```yml
name: Changelog
on:
release:
types:
- created
jobs:
changelog:
runs-on: ubuntu-latest
steps:
- name: "Auto Generate changelog"
uses: heinrichreimer/action-github-changelog-generator@v2.3
with:
token: $}}
```
This provided workflow will automatically populate the CHANGELOG.md with all of the associated changes created since the last release that are included in the current release.
This workflow will be triggered when a new release is created.
If you do not wish to use automatic changelogs, you can delete the workflow and update the CHANGELOG.md file manually. Although, this is not recommended.
## Hotfix Releases
In rare cases, a hotfix for a prior release may be required out-of-phase with the normal release cycle. For example, if a critical bug is discovered in the `0.3.x` line after `0.4.0` has already been released.
1. Create a _Support branch_ from the tag in `main` at which the hotfix is needed. For example if the bug was discovered in `0.3.2`, create a branch from this tag:
```bash
git fetch
git checkout 0.3.2
git checkout -b 0.3.x
git push -u origin 0.3.x
```
2. Merge (or commit directly) the hotfix work into this branch.
3. Tag the support branch with the hotfix version. For example if `0.3.2` is the version being hotfixed:
```bash
git fetch
git checkout 0.3.x
git tag 0.3.3
git push --tags
```
4. Create a [GitHub Release](proj-releases-new) from this tag and the support branch. For example if `0.3.3` is the new hotfix version:
```md
Tag version: 0.3.3
Target: 0.3.x
Release title: 0.3.3
Description: [copy in ReleaseNotes created earlier]
This is a pre-release: DO NOT check
```
[proj-releases-new]: https://github.com/DSACMS/gov-codejson/releases/new