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.

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
+```