diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cf1dc6e6..69178c31 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -43,3 +43,67 @@ The second, `versioned_docs` contains all of the specific Harper version documen Depending on the specific change, you may need to make updates to similar files across multiple version directories as well as the root `docs/`. The site organization is ever evolving so make sure to revisit this file over time to stay up to date with the latest structure. + +## Release Notes Process + +When adding release notes for a new HarperDB version, follow these steps: + +### 1. Create the Release Note File + +Add a new markdown file in the appropriate version directory: + +- Path: `release-notes/v4-tucker/{version}.md` (e.g., `4.7.1.md`) +- Include the standard frontmatter with title +- Add the date and version details +- List all changes, fixes, and improvements + +Example structure: + +```markdown +--- +title: 4.7.1 +--- + +# 4.7.1 + +MM/DD/YYYY + +- Feature or fix description +- Another change description +``` + +For alpha/beta releases, include the appropriate warning admonition. + +### 2. Update the Version Index (Minor Versions Only) + +For new minor versions (e.g., 4.8.0), update the version index file at `release-notes/v4-tucker/index.mdx`: + +- Add a new `` component section for the new minor version +- Include a summary of the major features introduced in that minor version line +- Place the newest minor version at the top of the file + +**Note**: For patch releases (e.g., 4.7.1, 4.7.2), you do NOT need to update the index file. The `` component automatically finds and links to the latest patch version. + +Example: + +```mdx +## + +- Major feature summary for 4.7.x releases +- Another significant capability added +``` + +### 3. Automatic Updates + +The following updates happen automatically through the system: + +- **Sidebar Navigation**: The release notes sidebar uses `autogenerated` directives, so new release note files are automatically included +- **Latest Version Links**: The `` component automatically finds and links to the latest patch version for a given major.minor combination +- **Sorting**: Release notes are automatically sorted by semantic version in the sidebar + +### 4. Considerations + +- Release notes are separate from the main documentation versioning system +- All release notes live in the `release-notes/` directory, not in `versioned_docs/` +- The release notes plugin is configured in `docusaurus.config.ts` with its own routing and sidebar +- The main navigation links directly to v4 Tucker release notes as the default