feat: Add precommit and git conventions (#775)

This commit moves our git conventions to their own
discrete page, and adds information that was previously
not written down anywhere, such as our general 
branch management strategy.

Beyond documenting these conventions, an initial pre-commit 
configuration has been added, which can be used as a guardrail 
to enforce some of the conventions, such as requirements 
around commit message length. A hook provided by the 
pre-commit maintainers is also configured to prevent 
commits directly to the main branch.

These configurations may be adjusted in the future based 
on feedback, and there is additional follow-up work to
add a template for the git commit message. I had a working 
implementation but decided to scrap it in favour of
minimising the number of dependencies.

Author: ADubhlaoich

.gitlint

@@ -0,0 +1,15 @@
+[general]
+ignore = body-is-missing
+contrib = contrib-title-conventional-commits
+
+[title-max-length] 
+line-length = 50
+
+[title-min-length]
+min-length = 5
+
+[body-max-line-length]
+line-length= 72
+
+[body-min-length]
+min-length = 5

.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+default_install_hook_types:
+    - pre-commit
+    - commit-msg
+
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0 
+    hooks:
+    -   id: no-commit-to-branch
+-   repo: https://github.com/jorisroovers/gitlint
+    rev:  v0.19.1
+    hooks:
+    -   id: gitlint

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing guidelines
 
-The following is a set of guidelines for community contributions to this project. 
+The following is a set of guidelines for community contributions to this project.
 
 We really appreciate your desire to contribute!
 
@@ -11,10 +11,7 @@ If you are an F5 employee, see the following additional guidance on [Maintainers
 - [Report a Bug](#report-a-bug)
 - [Suggest a Feature or Enhancement](#suggest-a-feature-or-enhancement)
 - [Open a Discussion](#open-a-discussion)
-- [Submit a Pull Request](#submit-a-pull-request)
-  - Review our [Git style guide](#git-style-guide)
-  - Review the [Writing style guide](/documentation/style-guide.md)
-  - Review [Managing content with Hugo](/documentation/writing-hugo.md)
+- [Submit a pull request](#submit-a-pull-request)
 - [Issue Lifecycle](#issue-lifecycle)
 - [Additional NGINX documentation](#additional-nginx-documentation)
 - [F5 Contributor License Agreement (CLA)](#f5-contributor-license-agreement)
@@ -37,44 +34,20 @@ If you want to start a conversation with the community and maintainers,
 we encourage you to use
 [GitHub Discussions](https://github.com/nginx/documentation/discussions).
 
-## Submit a Pull Request
+## Submit a pull request
 
-To contribute to F5 NGINX documentation, follow these steps:
+Before making documentation changes, you should view the [documentation style guide](/documentation/style-guide.md) and [Managing content with Hugo](/documentation/writing-hugo.md).
+
+To understand how we use Git in this repository, read our [Git conventions](/documentation/git-conventions.md) documentation.
+
+The broad workflow is as follows:
 
 - Fork the NGINX repository
 - Create a branch
 - Implement your changes in your branch
 - Submit a pull request (PR) when your changes are ready for review
 
-Alternatively, you're welcome to suggest improvements to highlight problems with
-our documentation as described in our [support](./SUPPORT.md) page.
-
-### Git style guide
-
-- Keep a clean, concise and meaningful Git commit history on your branch, rebasing locally and squashing before you submit a PR
-- We use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) formatting.
-- Follow the guidelines of writing a good commit message as described here <https://chris.beams.io/posts/git-commit/>
-  and summarized in the next few points:
-
-  - In the subject line, use the present tense ("Add feature" not "Added feature")
-  - In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to...")
-  - Limit the subject line to 72 characters or less
-  - Reference issues and pull requests liberally after the subject line
-  - Add more detailed description in the body of the git message (`git commit -a` to give you more space and time in
-    your text editor to write a good message instead of `git commit -am`)
-
-#### Branch protection rules
-
-This repository has the following branch protection rules in place:
-
-- **Pushing branches that contain the "internal/" prefix is not allowed.** This ensures internal development branches are not accidentally or purposefully pushed to this repo.
-- **Two approvers are required for all merges to main and release branches.** This ensures all code that is approved for release to production is appropriately reviewed. This rule applies to all branches with `*release*` in the branch name.
-- **Only NGINX DocOps Team members can create release branches.** This ensures the docs team is aware of all branches supporting specific product releases. This rule applies to all branches with `*release*` in the branch name.
-- **Pushes (force or otherwise) directly to main or release branches is not allowed.** Release branches serve as "main" for the release they are associated with. Restricting pushes directly to main and release branches ensures all content changes are reviewed and approved. This rule applies to all branches with `*release*` in the branch name and to "main".
-
-### Documentation style guide
-
-For detailed guidance, see our documentation [style guide](./templates/style-guide.md).
+Alternatively, you're welcome to suggest improvements to highlight problems with our documentation as described in our [support](./SUPPORT.md) page.
 
 ## Issue lifecycle
 

documentation/README.md

@@ -1,4 +1,4 @@
-# NGINX Documentation repository 
+# NGINX Documentation repository
 
 This directory contains the documentation for the NGINX Documentation repository.
 
@@ -13,8 +13,10 @@ If you're interested in contributing to the [NGINX documentation website](https:
 ## Topics
 
 - [Contributing closed content](/documentation/closed-contributions.md)
+- [Git conventions](/documentation/git-conventions.md)
 - [Information architecture heuristics](/documentation/ia-heuristics.md)
 - [Maintainers etiquette](/documentation/maintainers-etiquette.md)
 - [Managing content with Hugo](/documentation/writing-hugo.md)
 - [Proposals](/documentation/proposals/README.md)
+- [Set up pre-commit](/documentation/pre-commit.md)
 - [Writing style guide](/documentation/style-guide.md)

documentation/git-conventions.md

@@ -0,0 +1,83 @@
+# Git conventions
+
+For consistency, we have a handful of git conventions:
+
+- We follow a [GitHub flow model](https://githubflow.github.io/) for branch management
+- We follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) formatting
+- We write [good commit messages](https://cbea.ms/git-commit/), treating them as a source of truth
+
+Many of these conventions are suggested or enforced in tooling: for local development, [set up pre-commit](/documentation/pre-commit.md).
+
+We encourage small, tightly-scoped pull requests: this makes managing reviews simpler, allowing us to iterate on documentation quickly.
+
+## Branch management
+
+We continuously deploy from the [`main`](https://github.com/nginx/documentation/tree/main) branch.
+
+To make changes, [fork the repository](https://github.com/nginx/documentation/fork) then branch from `main`, giving your branch a prefix and descriptive name.
+
+Prefixes are typically a three letter acronym for the product it affects:
+- `nic/`, `ngf/`, `nim`/, `waf/`, and so forth
+-  Use `docs/` if the change is related to the repository or not product-specific
+
+A descriptive name usually concerns what the branch actually updates:
+- `nic/update-helm-links` Tells someone at a glance that the branch relates to NGINX Ingress Controller and links related to Helm
+- `patch-27` Tells someone almost nothing at a glance: it does not include a prefix or any details about a possible topic
+
+The exception to this branch naming convention is release branches for products. These are named `<product>-<release>-<version>`:
+- `agent-release-2.2`
+- `n1c-release-1.5`
+- `dos-release-5.1`
+
+Typically, the technical writer for a given product will ensure that branches are kept in sync with `main`, to minimize the risk of merge conflicts.
+
+If you need to rename a branch, here's the syntax:
+
+```shell
+git branch -m <current-branch-name> <new-branch-name>
+```
+
+## Commit messages
+
+When opening a pull request on GitHub, the very first commit from a branch is automatically pulled to populate the description.
+
+This provides an opportunity to re-use a good commit message to provide context to reviewers for the changes in a branch.
+
+The first line of a git commit message becomes the subject line, with the contents after a line break becoming the body.
+
+A subject line begins with a [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) prefix, and should be written in present imperative.
+- _feat: Update ConfigMap reference page_
+- _fix: Remove links to missing website_
+
+Keep the subject line around 50 characters or less: imagine the reader is using `git reflog` or `git log --oneline` to review changes.
+
+The body of the git message should have its lines kept around 72 characters or less, and can be structured as follows:
+
+- What was changed and why
+- How the changes were implemented
+- What else the changes might affect, and what may change in the future
+
+This provides enough context for a reader to get a strong impression of what the commit accomplishes, which in turn makes reviewing pull requests easier
+
+An example of a full commit message following the above conventions is as follows:
+
+```
+feat: Move and update process documentation
+
+This commit moves and updates some of the process documentation for the
+repository. This is an iterative process, which will continue to improve
+as time goes on. Some of the changes include:
+
+- Moving the closed contributions document into the documentation folder
+- Moving and reframing the F5/NGINX document as "Maintainers etiquette"
+- Moving and renaming the "Managing content with Hugo" document
+- Moving the style guide from the templates folder
+
+These files will likely be updated in a subsequent PR as we clarify the
+contribution process and user flow of other process artefacts, such as
+the pull request and issue templates.
+
+Although we do not draw attention to it, the templates folder is being
+retained for reference until the style guide and Hugo archetypes contain
+the relevant, useful information.
+```

documentation/pre-commit.md

@@ -0,0 +1,33 @@
+# Set up pre-commit
+
+[pre-commit](https://pre-commit.com/) is a command-line tool used for automatic linting.
+
+It is currently *optional*, and used for consistent [Git conventions](/documentation/git-conventions.md), but will be used for more in the future.
+
+The configuration file is located at the root of the repository, [pre-commit-config.yaml](/.pre-commit-config.yaml).
+
+## Install pre-commit
+
+To install pre-commit, you need [pip](https://pypi.org/project/pip/), which is bundled with most contemporary Python installations.
+
+After ensuring you have pip installed, follow the [Installation steps](https://pre-commit.com/#install):
+
+```shell
+pip install pre-commit
+```
+
+Then install the git hook scripts with the following command:
+
+```shell
+pre-commit install
+```
+
+It will then run every time you use `git commit`.
+
+If you encounter an error about a missing configuration file, you are likely working in a branch that has not synced changes from `main`.
+
+You will need to sync changes from `main` or temporarily uninstall pre-commit to address the error.
+
+```shell
+pre-commit uninstall
+```