Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history 
Signed-off-by: Natalia Luzuriaga <natalia.luzuriaga@cms.hhs.gov>
  • Loading branch information
@natalialuzuriaga
natalialuzuriaga committed Feb 13, 2025
1 parent 139ded8 commit b18dd40
Show file tree
Hide file tree
Showing 3 changed files with 247 additions and 16 deletions.
6 changes: 4 additions & 2 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,9 @@ authorship metadata will be preserved.
<!--
## Shipping Releases
<!-- TODO: What cadence does your project ship new releases? (e.g. one-time, ad-hoc, periodically, upon merge of new patches) Who does so?
Our general policy for shipping releases can be found in our [MAINTAINERS.md](./MAINTAINERS.md) file. We adhere to semantic versioning and automatic generation of changelogs as described in this file.
<!-- TODO: What cadence does your project ship new releases? (e.g. one-time, ad-hoc, periodically, upon merge of new patches) Who does so?
-->

## Documentation
Expand All @@ -174,7 +176,7 @@ questions, just [shoot us an email](mailto:opensource@cms.hhs.gov).

### Security and Responsible Disclosure Policy

*Submit a vulnerability:* Vulnerability reports can be submitted through [Bugcrowd](https://bugcrowd.com/cms-vdp). Reports may be submitted anonymously. If you share contact information, we will acknowledge receipt of your report within 3 business days.
_Submit a vulnerability:_ Vulnerability reports can be submitted through [Bugcrowd](https://bugcrowd.com/cms-vdp). Reports may be submitted anonymously. If you share contact information, we will acknowledge receipt of your report within 3 business days.

For more information about our Security, Vulnerability, and Responsible Disclosure Policies, see [SECURITY.md](SECURITY.md).

Expand Down
251 changes: 242 additions & 9 deletions MAINTAINERS.md
View file
Original file line number Diff line number Diff line change
@@ -1,27 +1,260 @@
# Maintainers

<!-- TODO: Who are the points of contact in your project who are responsible/accountable for the project? This can often be an engineering or design manager or leader, who may or may not be the primary maintainers of the project.-->

This is a list of maintainers for this project. See [CODEOWNERS.md](./CODEOWNERS.md) for list of reviewers for different parts of the codebase. Team members include:

## Maintainers:

<!-- TODO: What groups/domains are maintainers a part of? Does your project have domains/areas that are maintained by specific people? List @USERNAMES directly, or any @ALIASES for groups/teams.-->
-

-

## Approvers:
-

-

## Reviewers:
-

| 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|
-

| 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

<!-- In order to automatically update the MAINTAINERS.md, you must enter a secret into your Secrets and Variables under Actions within your repository settings. The name of the secret must be PUSH_TO_PROTECTED_BRANCH and the value must be a Personal Access Token with specific permissions. Please follow [this link](https://github.com/CasperWA/push-protected?tab=readme-ov-file#notes-on-token-and-user-permissions) for more information. -->

Total number of contributors: <!--CONTRIBUTOR COUNT START--> <!--CONTRIBUTOR COUNT END-->

<!-- readme: contributors -start -->
<!-- readme: contributors -end -->

# Tier 3 Release Guidelines

{{ cookiecutter.project_repo_name }} 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)
<!-- * [Breaking vs. non-breaking changes](#breaking-vs-non-breaking-changes) -->
- [Ongoing version support](#ongoing-version-support)
- [Release Process](#release-process)
- [Goals](#goals)
- [Schedule](#schedule)
- [Communication and Workflow](#communication-and-workflow)
<!-- * [Beta Features](#beta-features) -->
- [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

{{ cookiecutter.project_repo_name }} uses [Semantic Versioning](https://semver.org/). Each release is associated with a [`git tag`](github.com/{{ cookiecutter.project_org }}/{{ cookiecutter.project_repo_name }}/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

<!-- ### Breaking vs. non-breaking changes -->

<!--- TODO: Examples and protocol for breaking changes
Definitions for breaking changes will vary depending on the use-case and project but generally speaking if changes break standard workflows in any way then they should be put in a major version update.
-->

### Ongoing version support

<!-- TODO: Explanation of general thought process
Explain the project’s thought process behind what versions will and won’t be supported in the future.
-->

<!-- TODO: List of supported releases
This section should make clear which versions of the project are considered actively supported.
-->

## Release Process

The sections below define the release process itself, including timeline, roles, and communication best practices.

### Goals

<!-- TODO: Explain the goals of your project’s release structure
This should ideally be a bulleted list of what your regular releases will deliver to key users and stakeholders
-->

.

### Schedule

<!-- TODO: Communicate the timing of the regular release structure
For example, if you plan on creating regular releases on a weekly basis you should communicate that as well as the typical days upcoming releases will become tagged.
You should also communicate special cases such as security updates or critical bugfixes and how they would likely be released earlier than what is usually scheduled.
-->

### Communication and Workflow

<!-- TODO: Communicate proper channels to be notified about releases
Communicate the slack channels, mailing lists, or other means of pushing out release notifications.
-->

<!-- TODO: (OPTIONAL) Support beta feature testing
## Beta Features
When a new beta feature is created for a release, make sure to create a new Issue with a '[Feature Name] - Beta [X.X.x] - Feedback' title and a 'beta' label. Update the spec text for the beta feature with 'Beta feature: Yes (as of X.X.x). Leave feedback' with a link to the new feature Issue.
Once an item is moved out of beta, close its Issue and change the text to say 'Beta feature: No (as of X.X.x)'.
-->

## Preparing a Release Candidate

The following steps outline the process to prepare a Release Candidate of {{ cookiecutter.project_repo_name }}. 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 {{ cookiecutter.project_repo_name }}:

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:
{% raw %}
token: ${{{{ secrets.GITHUB_TOKEN }}}}
{% endraw %}
```

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/{{ cookiecutter.project_org }}/{{ cookiecutter.project_repo_name }}/releases/new
6 changes: 1 addition & 5 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,11 +33,7 @@ An up-to-date list of core team members can be found in [MAINTAINERS.md](MAINTAI
## Repository Structure

<!-- TODO: Using the "tree -d" command can be a helpful way to generate this information, but, be sure to update it as the project evolves and changes over time.-->

```plaintext
.
```

<!--TREE START--><!--TREE END-->

**{list directories and descriptions}**

Expand Down

0 comments on commit b18dd40

Please sign in to comment.