Clarify changelog fragment workflow for contributors
- Dominant language
- Go
- Stars
- 36.3k
- Forks
- 4.8k
- PR merge metrics
- PR metrics pending
Description
## Summary
I opened this as a repository documentation/file-management improvement suggestion, but the original issue body was accidentally pasted as a JSON object and included a few overbroad claims. Reframing this into a narrower, more actionable docs request.
Vault already has many of the expected repository files and docs in place:
- root `CHANGELOG.md`
- granular `changelog/` entries
- `.github/ISSUE_TEMPLATE/`
- `.github/ISSUE_TEMPLATE.md`
- `.github/pull_request_template.md`
- `.github/CODE_OF_CONDUCT.md`
- README links to docs, tutorials, forum, development setup, testing, and troubleshooting
The remaining improvement I wanted to suggest is mostly about contributor clarity.
## Problem
For a new or occasional contributor, it is not immediately obvious how the root `CHANGELOG.md` and the `changelog/` fragment directory relate to each other.
Because both exist, contributors may wonder:
- Should a PR add a new file under `changelog/`?
- Is `CHANGELOG.md` generated from fragments or manually maintained?
- What filename/category format should a changelog fragment use?
- Are there changes that should not receive a changelog entry?
This is not a request to remove either changelog mechanism. It is a request to document the intended workflow more explicitly.
## Suggested Improvements
### 1. Add changelog contributor guidance
Add a short `changelog/README.md` or a section in `CONTRIBUTING.md`/the PR template that explains:
- when to add a changelog fragment;
- expected filename format;
- expected content/category format;
- how fragments are collected into release notes or `CHANGELOG.md`;
- examples of changes that do and do not need changelog entries.
### 2. Link changelog guidance from the PR template
If Vault expects changelog fragments for user-facing changes, the PR template could include a small checklist item such as:
```md
- [ ] Added a changelog fragment, or confirmed this change does not need one.
```
### 3. Optional README contributor pointer
The README already links to user docs and developer setup. A small contributor pointer could help route people toward the right docs before opening PRs, for example:
```md
For contribution workflow, changelog entries, and PR expectations, see CONTRIBUTING.md.
```
## Non-goals
- Do not remove `CHANGELOG.md`.
- Do not remove the `changelog/` fragment directory.
- Do not replace existing GitHub issue/PR templates.
- Do not duplicate product documentation already maintained on developer.hashicorp.com.
## Why this helps
This would reduce uncertainty for contributors and make changelog expectations easier to follow without changing Vault's existing release process.
Contributor guide
Research direction
Start by comparing the root CHANGELOG.md, the changelog/ directory, and the contributor-facing files mentioned in the issue, including CONTRIBUTING.md and .github/pull_request_template.md. Document the existing fragment workflow, filename and category rules, and when entries are optional; done means contributors can follow the process without guessing and the relevant guidance is linked from the PR template.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 72/100