hashicorp / hashicorp/vault

Clarify changelog fragment workflow for contributors

Open
#32,030 0 comments 1 reaction 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.