Skip to content

Commit 792d2f9

Browse files
committed
Update contributing docs and PR template for changelog fragments
The fragment-based changelog system landed in isaac-sim#5434. Two contributor- facing references still pointed at the old "edit CHANGELOG.rst directly" workflow: - docs/source/refs/contributing.rst — Maintaining a changelog and extension.toml section described per-version editing of CHANGELOG.rst with manual SemVer bumps. - .github/PULL_REQUEST_TEMPLATE.md — checklist item asked contributors to update the changelog and bump extension.toml. Replaced the directly-affected paragraphs and the sample with the fragment workflow. Section/style guidance (Added/Changed/Deprecated/ Removed/Fixed, past tense, sample bullets) stays verbatim.
1 parent d3ce0b3 commit 792d2f9

2 files changed

Lines changed: 18 additions & 16 deletions

File tree

.github/PULL_REQUEST_TEMPLATE.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ To upload images to a PR -- simply drag and drop an image while in edit mode and
4747
- [ ] I have made corresponding changes to the documentation
4848
- [ ] My changes generate no new warnings
4949
- [ ] I have added tests that prove my fix is effective or that my feature works
50-
- [ ] I have updated the changelog and the corresponding version in the extension's `config/extension.toml` file
50+
- [ ] I have added a changelog fragment under `source/<pkg>/changelog.d/` for every touched package (do **not** edit `CHANGELOG.rst` or bump `extension.toml` — CI handles that)
5151
- [ ] I have added my name to the `CONTRIBUTORS.md` or my name already exists there
5252

5353
<!--

docs/source/refs/contributing.rst

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -149,20 +149,28 @@ for each version of the extension.
149149

150150
.. note::
151151

152-
The version number on the ``extension.toml`` file should be updated according to
153-
`Semantic Versioning <https://semver.org/>`__ and should match the version number in the
154-
``CHANGELOG.rst`` file.
152+
``CHANGELOG.rst`` and ``extension.toml`` are compiled by CI from per-PR **fragment
153+
files** — contributors do not edit them directly. For every package your PR touches
154+
in ``source/<package>/`` (outside ``changelog.d/``), add one fragment under
155+
``source/<package>/changelog.d/<slug>.<tier>.rst``:
156+
157+
* ``<slug>.rst`` — patch bump
158+
* ``<slug>.minor.rst`` — minor bump (new public API)
159+
* ``<slug>.major.rst`` — major bump (breaking change)
160+
* ``<slug>.skip`` — no entry, no bump (CI / docs / test-only PRs)
161+
162+
``<slug>`` is any short, unique name; your branch name with ``/`` replaced by ``-``
163+
is the recommended default. Within a batch the highest tier wins for the package.
164+
The version on ``extension.toml`` is bumped by CI according to
165+
`Semantic Versioning <https://semver.org/>`__.
155166

156167
The changelog file is written in `reStructuredText <https://docutils.sourceforge.io/rst.html>`__ format.
157168
The goal of this changelog is to help users and contributors see precisely what notable changes have
158169
been made between each release (or version) of the extension. This is a *MUST* for every extension.
159170

160-
For updating the changelog, please follow the following guidelines:
171+
For each fragment, please follow the following guidelines:
161172

162-
* Each version should have a section with the version number and the release date.
163-
* The version number is updated according to `Semantic Versioning <https://semver.org/>`__. The
164-
release date is the date on which the version is released.
165-
* Each version is divided into subsections based on the type of changes made.
173+
* Each fragment is divided into subsections based on the type of changes made.
166174

167175
* ``Added``: For new features.
168176
* ``Changed``: For changes in existing functionality.
@@ -182,16 +190,10 @@ For updating the changelog, please follow the following guidelines:
182190

183191
When in doubt, please check the style in the existing changelog files and follow the same style.
184192

185-
For example, the following is a sample changelog:
193+
For example, ``source/isaaclab/changelog.d/<slug>.minor.rst``:
186194

187195
.. code:: rst
188196
189-
Changelog
190-
---------
191-
192-
0.1.0 (2021-02-01)
193-
~~~~~~~~~~~~~~~~~~
194-
195197
Added
196198
^^^^^
197199

0 commit comments

Comments
 (0)