From 0f313e2b4d6737f15bd69e3d9c7761360bd43f76 Mon Sep 17 00:00:00 2001 From: Andrew Clayton Date: Tue, 9 Jul 2024 02:11:55 +0100 Subject: CONTRIBUTING.md: Re-flow text Re-flow text to wrap a little before the 80 column mark, this improves the reading/editing experience in standard ANSI terminals and also improves the diffing by reducing the amount of wrapping that then occurs with the +/- additions. This is a preparatory patch for future editing of this document. Signed-off-by: Andrew Clayton --- CONTRIBUTING.md | 37 +++++++++++++++++++------------------ 1 file changed, 19 insertions(+), 18 deletions(-) (limited to 'CONTRIBUTING.md') diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 77343271..2d8bd230 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,15 +14,16 @@ appreciate that you are considering contributing! ## Getting Started Check out the [Quick Installation](README.md#quick-installation) and -[Howto](https://unit.nginx.org/howto/) guides to get NGINX Unit up and running. +[Howto](https://unit.nginx.org/howto/) guides to get NGINX Unit up and +running. ## Ask a Question -Please open an [issue](https://github.com/nginx/unit/issues/new) on GitHub with -the label `question`. You can also ask a question on -[GitHub Discussions](https://github.com/nginx/unit/discussions) or the NGINX Unit mailing list, -unit@nginx.org (subscribe +Please open an [issue](https://github.com/nginx/unit/issues/new) on GitHub +with the label `question`. You can also ask a question on +[GitHub Discussions](https://github.com/nginx/unit/discussions) or the NGINX +Unit mailing list, unit@nginx.org (subscribe [here](https://mailman.nginx.org/mailman3/lists/unit.nginx.org/)). @@ -47,17 +48,17 @@ the expected behavior that doesn't occur. To suggest an enhancement, open an [issue](https://github.com/nginx/unit/issues/new) on GitHub with the label -`enhancement`. Please do this before implementing a new feature to discuss the -feature first. +`enhancement`. Please do this before implementing a new feature to discuss +the feature first. ### Open a Pull Request -Before submitting a PR, please read the NGINX Unit code guidelines to know more -about coding conventions and benchmarks. Fork the repo, create a branch, and -submit a PR when your changes are tested and ready for review. Again, if you'd -like to implement a new feature, please consider creating a feature request -issue first to start a discussion about the feature. +Before submitting a PR, please read the NGINX Unit code guidelines to know +more about coding conventions and benchmarks. Fork the repo, create a branch, +and submit a PR when your changes are tested and ready for review. Again, if +you'd like to implement a new feature, please consider creating a feature +request issue first to start a discussion about the feature. ## Git Style Guide @@ -66,13 +67,13 @@ issue first to start a discussion about the feature. rebasing locally and squashing before submitting a PR - For any user-visible changes, updates, and bugfixes, add a note to - `docs/changes.xml` under the section for the upcoming release, using `` for new functionality, `` for changed - behavior, and `` for bug fixes. + `docs/changes.xml` under the section for the upcoming release, using + `` for new functionality, `` + for changed behavior, and `` for bug fixes. -- In the subject line, use the past tense ("Added feature", not "Add feature"); - also, use past tense to describe past scenarios, and present tense for - current behavior +- In the subject line, use the past tense ("Added feature", not "Add + feature"); also, use past tense to describe past scenarios, and present + tense for current behavior - Limit the subject line to 67 characters, and the rest of the commit message to 80 characters -- cgit From 202242790764bf38aa4f4598f787175b9cc7e4ef Mon Sep 17 00:00:00 2001 From: Andrew Clayton Date: Tue, 9 Jul 2024 02:37:23 +0100 Subject: CONTRIBUTING.md: Update the 'Git Style Guide' section This makes it reflect current reality. NOTE: This removes the bit about updating the changes.xml file. For me that has been a constant source of problems. Especially when it hasn't been done as a separate commit (makes reverting changes harder due to this file being constantly re-worked). This file is also usually re-worked at release time, with the re-wording and re-ordering of items. In my experience it is much better to leave the updating of this file to release time when you can use 'git shortlog -e ..' as the source for adding entries to the changelog. Signed-off-by: Andrew Clayton --- CONTRIBUTING.md | 41 ++++++++++++++++++++++------------------- 1 file changed, 22 insertions(+), 19 deletions(-) (limited to 'CONTRIBUTING.md') diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2d8bd230..eeee56cb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -63,29 +63,32 @@ request issue first to start a discussion about the feature. ## Git Style Guide -- Keep a clean, concise and meaningful `git commit` history on your branch, - rebasing locally and squashing before submitting a PR +- Create atomic commits. A commit should do just one thing, i.e. you + shouldn't mix refactoring with functional code changes. Do the + refactoring in one or more commits first. -- For any user-visible changes, updates, and bugfixes, add a note to - `docs/changes.xml` under the section for the upcoming release, using - `` for new functionality, `` - for changed behavior, and `` for bug fixes. + Ideally you should rebase locally and force push new commits up. -- In the subject line, use the past tense ("Added feature", not "Add - feature"); also, use past tense to describe past scenarios, and present - tense for current behavior +- In the subject line, use the imperative mood. I.e. write the subject like + you're giving git a command, e.g. "Free memory before exiting". Do not + terminate the subject with a `.` -- Limit the subject line to 67 characters, and the rest of the commit message - to 80 characters +- Try to limit the subject line to around 50 characters, but try not to + exceed 72. -- Use subject line prefixes for commits that affect a specific portion of the - code; examples include "Tests:", "Packages:", or "Docker:", and also - individual languages such as "Java:" or "Ruby:" +- Wrap the body of the commit message after 72 characters. -- Reference issues and PRs liberally after the subject line; if the commit - remedies a GitHub issue, [name - it](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) - accordingly +- Use lowercase subject line prefixes for commits that affect a specific + portion of the code; examples include "tests:", "ci:", or "http:", and + also individual languages such as "python:" or "php:". If multiple areas + are affected you can specify multiple prefixes, e.g. "auto, perl:" -- Don't rely on command-line commit messages with `-m`; use the editor instead +- If the commit fixes an open issue then you can use the "Closes:" + tag/trailer to reference it and have GitHub automatically close it once + it's been merged. E.g.: + + `Closes: https://github.com/nginx/unit/issues/9999` + + That should go at the end of the commit message, separated by a blank line, + along with any other tags. -- cgit