~jan0sch/smederee

Showing details for patch 352096dd18684509e67b55cea0e0fe9923e38867.
2023-05-03 (Wed), 12:56 PM - Jens Grassel - 352096dd18684509e67b55cea0e0fe9923e38867

Adjust contribution guide.

- clear several todo items regarding patch commission and review
- extend patch requirements
- introduce markers and reference linux kernel docs for more details
Summary of changes
1 files modified with 18 lines added and 6 lines removed
  • CONTRIBUTING.md with 18 added and 6 removed lines
diff -rN -u old-smederee/CONTRIBUTING.md new-smederee/CONTRIBUTING.md
--- old-smederee/CONTRIBUTING.md	2025-01-31 02:46:50.297852436 +0000
+++ new-smederee/CONTRIBUTING.md	2025-01-31 02:46:50.297852436 +0000
@@ -41,8 +41,14 @@
 7. A patch commit message MUST consist of a single short (less than 80 characters) line stating the problem being solved, followed by a blank line and then the proposed solution and summary of changes. The description is not limited and may span over multiple paragraphs. Please use proper English syntax, grammar and punctuation and imperative mood e.g. "add visual highlighting" instead of "[This] adds visual highlighting." or "I changed the code rendering to include visual highlighting"
 8. A patch fixing a ticket MUST include a trailing `Fixes:` line in the commit message that links to the ticket, for example: `Fixes: https://tickets.smeder.ee/~jan0sch/smederee/123`
 9. A patch fixing a regression of another patch MUST include a trailing `Fixes:` line referencing the other patch by its hash, for example: `Fixes: 0b8e86ad1f6a182433d2f59ebf2d40b9b8931f50`
-10. 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.
-11. A "Correct Patch" is one that satisfies the above requirements.
+10. A patch not related to an issue SHOULD include either `Reported-by: alias/name <email>` or `Suggested-by: alias/name <email>` markers to give proper credit for people reporting bugs and suggesting features that are themselves not providing patches.
+  1. If the aforementioned people did not report/suggest in public form (mailing list, forum) then they MUST be asked for permission before adding the markers.
+  2. `Reported-by:` markers MUST ONLY be used for bugs.
+  3. `Suggested-by:` markers MUST NEVER be used for bugs.
+11. 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.
+12. A "Correct Patch" is one that satisfies the above requirements.
+
+More information about the process of reported and suggested marker usage (also called trailers) can be found in the [Linux kernel development documentation](https://www.kernel.org/doc/html/latest/process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes).
 
 ### 3.4 Development Process
 
@@ -53,11 +59,13 @@
 5. Users SHALL NOT log feature requests, ideas, suggestions, or any solutions to problems that are not explicitly documented and provable.
 6. Thus, the release history of the project SHALL be a list of meaningful issues logged and solved.
 7. To work on an issue, a Contributor SHALL fork the project repository and then work on their forked repository.
-8. **TODO**: To submit a patch, a Contributor SHALL create a Platform pull request back to the project. ???
+8. To submit a patch, a Contributor SHALL send the patch to the project mailing list.
 9. A Contributor SHALL NOT commit changes directly to the project.
-10. **TODO**: If the Platform implements pull requests as issues, a Contributor MAY directly send a pull request without logging a separate issue. ???
-11. **TODO**: To discuss a patch, people MAY comment on the Platform pull request, on the commit, or elsewhere. ???
-12. TODO: To accept or reject a patch, a Maintainer SHALL use the Platform interface. ???
+10. A Contributor MAY directly send a patch without logging a separate issue.
+11. To discuss a patch, people MAY comment on the mailing list using markers (trailers) as described below:
+  1. `Tested-by: alias/name <email>` to indicate that the patch has been successfully applied and tested by the person named (in some environment).
+  2. `Reviewed-by: alias/name <email>` to indicate that the patch has been reviewed and found acceptable.
+12. To accept or reject a patch, a Maintainer SHALL reply on the mailing list and include the `Acked-by: alias/name <email>` marker upon acceptance of the patch into the main branch.
 13. Maintainers SHOULD NOT merge their own patches except in exceptional cases, such as non-responsiveness from other Maintainers for an extended period (more than 1-2 days).
 14. Maintainers SHALL NOT make value judgements on correct patches.
 15. Maintainers SHALL merge correct patches from other Contributors rapidly.
@@ -66,6 +74,8 @@
 18. Any Contributor who has value judgements on a patch SHOULD express these via their own patches.
 19. Maintainers SHOULD close user issues that are left open without action for an uncomfortable period of time.
 
+More information about the process of marker usage (also called trailers) can be found in the [Linux kernel development documentation](https://www.kernel.org/doc/html/latest/process/submitting-patches.html#when-to-use-acked-by-cc-and-co-developed-by).
+
 ### 3.5 Branches and Releases
 
 In darcs, each repository is a branch. Therefore what you would consider a fork in other systems like git, is considered a branch in darcs.
@@ -73,6 +83,8 @@
 1. The project SHALL have one main branch that always holds the latest in-progress version and SHOULD always build.
 2. 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.
 
+TODO: Adjust releases and tagging to having multiple modules inside the mono repository.
+
 #### 3.5.1 Release guide
 
 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."