~jan0sch/smederee

Showing details for patch cc27fb699b764dff8e7f040838864087404f7f2c.
2023-02-18 (Sat), 8:29 AM - Jens Grassel - cc27fb699b764dff8e7f040838864087404f7f2c

CONTRIBUTING: Updates regarding CHANGELOG handling and releases.

- reduce number of links to CHANGELOG file to reduce clutter
- remove `.md` suffix in link names
Summary of changes
1 files modified with 11 lines added and 8 lines removed
  • CONTRIBUTING.md with 11 added and 8 removed lines
diff -rN -u old-smederee/CONTRIBUTING.md new-smederee/CONTRIBUTING.md
--- old-smederee/CONTRIBUTING.md	2025-01-31 16:53:51.888836768 +0000
+++ new-smederee/CONTRIBUTING.md	2025-01-31 16:53:51.888836768 +0000
@@ -17,7 +17,7 @@
 1. The project SHALL use the darcs distributed revision control system.
 2. The project SHALL be hosted on [Smederee](https://smeder.ee), herein called the "Platform".
 3. The project SHALL use the Platform issue tracker.
-4. The project SHOULD have clearly documented guidelines for code style. The code style is documented in the file [CODINGSTYLE.md](CODINGSTYLE.md) in the project root.
+4. The project SHOULD have clearly documented guidelines for code style. The code style is documented in the file [CODINGSTYLE](CODINGSTYLE.md) in the project root.
 5. A "Contributor" is a person who wishes to provide a patch, being a set of commits that solve some clearly identified problem.
 6. A "Maintainer" is a person who merges patches to the project. Maintainers are not developers; their job is to enforce process.
 7. Contributors SHALL NOT have commit access to the repository unless they are also Maintainers.
@@ -28,7 +28,7 @@
 
 1. The project SHALL use the AGPL 3.0 or later (see [LICENSE](LICENSE)).
 2. All contributions to the project source code ("patches") SHALL use the same license as the project.
-3. All patches are owned by their authors. There SHALL NOT be any copyright assignment process. Each Contributor SHALL be responsible for identifying themselves in the project Contributor list which is located in the file [AUTHORS.md](AUTHORS.md) in the project root.
+3. All patches are owned by their authors. There SHALL NOT be any copyright assignment process. Each Contributor SHALL be responsible for identifying themselves in the project Contributor list which is located in the file [AUTHORS](AUTHORS.md) in the project root.
 
 ### 3.3 Patch Requirements
 
@@ -39,7 +39,8 @@
 5. A patch SHALL NOT include non-trivial code from other projects unless the Contributor is the original author of that code.
 6. A patch MUST compile cleanly and pass project self-tests on at least the principal target platform.
 7. A patch commit message MUST consist of a single short (less than 70 characters) line stating the problem being solved, followed by a blank line and then the proposed solution and summary of changes. If the patch addresses an issue from the issue tracker then the title line should instead contain the issue number and title (e.g. "ISSUE-NUMBER Issue summary").
-8. A "Correct Patch" is one that satisfies the above requirements.
+8. A patch MUST NOT update the [CHANGELOG](CHANGELOG.md) file because that might introduce dependencies between unrelated patches due to modification of related lines within the CHANGELOG.
+9. A "Correct Patch" is one that satisfies the above requirements.
 
 ### 3.4 Development Process
 
@@ -67,17 +68,19 @@
 
 1. The project SHALL have one main branch that always holds the latest in-progress version and SHOULD always build.
 2. The project SHALL NOT use topic branches for any reason. Personal forks MAY use topic branches.
-3. To make a stable release a Maintainer shall tag the repository. Stable releases SHALL always be released from the main branch.
+3. To make a stable release a Maintainer SHALL prepare the CHANGELOG file and tag the repository. Stable releases SHALL always be released from the main branch.
 
 #### 3.5.1 Release guide
 
-The changes in the section `Unreleased` in the [CHANGELOG.md](CHANGELOG.md) file MUST be moved to a section named after the release and a new empty `Unreleased` section MUST be created.
+Before releasing a new version a Maintainer SHALL update the [CHANGELOG](CHANGELOG.md) file and add the changes which are subject to the release. The changes SHOULD be written into the `Unreleased` section of the file and the commit message SHALL be titled "CHANGELOG: Update with changes since the last release."
 
-The release `NAME` shall follow the specification described in the CHANGELOG file e.g. `major`.`minor`.`patchlevel` prefixed with a lower case `v`, for example: `v1.0.3`.
+The release `NAME` SHALL follow the specification described in the CHANGELOG file e.g. `major`.`minor`.`patchlevel` prefixed with a lower case `v`, for example: `v1.0.3`.
 
-A release SHALL be accompanied by an annotated tag (`darcs tag --edit-long-comment NAME`) that holds a description of the changes that are included in the release. This description SHOULD be same as in the file [CHANGELOG.md](CHANGELOG.md).
+IMMEDIATELY BEFORE the release, the changes in the section `Unreleased` in the [CHANGELOG](CHANGELOG.md) file MUST be moved to a section named after the release and a new empty `Unreleased` section MUST be created. The commit message for these changes MUST be titled "Prepare RELEASE NAME" e.g. "Prepare RELEASE v1.2.3"
 
-Please note that lines starting with `#` are ignored by darcs therefore the sections like `Added`, `Fixed` etc. SHALL be written in the alternate heading syntax of markdown. Example:
+A release SHALL be accompanied by an annotated tag (`darcs tag --edit-long-comment NAME`) that holds a description of the changes that are included in the release. This description SHOULD be same as in the CHANGELOG.
+
+Please note that lines starting with a hash (`#`) are ignored by darcs therefore the sections like `Added`, `Fixed` etc. MUST be written in the alternate heading syntax of markdown. Example:
 
 ```
 v0.2.0