Skip to content

Commit 19b159d

Browse files
committed
fix: update readme for forking process
1 parent 3f5ff52 commit 19b159d

File tree

1 file changed

+52
-5
lines changed

1 file changed

+52
-5
lines changed

docs/readme.md

Lines changed: 52 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,15 +12,62 @@ In this directory, you will find the following files:
1212
- configuration files for [markdownlint](https://github.com/DavidAnson/markdownlint/) and [markdown-link-check](https://github.com/tcort/markdown-link-check)
1313
- a `./config` directory that contains the [Hugo](https://gohugo.io) configuration.
1414

15-
## Git workflow
15+
## Git Guidelines
1616

17-
To contribute to the documentation, create your work branch from the `main` branch. Once you have added your changes, open a PR to merge your changes back to `main`.
17+
- Keep a clean, concise and meaningful git commit history on your branch (within reason), rebasing locally and squashing before submitting a PR.
18+
- Use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format when writing a commit message, so that changelogs can be automatically generated
19+
- Follow the guidelines of writing a good commit message as described here <https://chris.beams.io/posts/git-commit/> and summarised in the next few points:
20+
- In the subject line, use the present tense ("Add feature" not "Added feature").
21+
- In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to...").
22+
- Limit the subject line to 72 characters or less.
23+
- Reference issues and pull requests liberally after the subject line.
24+
- 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`).
1825

19-
Netlify will create a preview of the documentation and add a link to the GitHub PR page.
26+
### Forking and Pull Requests
2027

21-
Once the preview and the changes have been reviewed, merge the request to the `main` branch.
28+
This repo uses a [forking workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow). Take the steps below to fork the repo, check out a feature branch, and open a pull request with your changes.
2229

23-
> NOTE: If you want to test changes in an environment that emulates the production site before updating `main`, you can push your changes to `docs-development` or `docs-staging`. These branches deploy to the nginx docs [dev](https://docs-dev.nginx.com) and [staging](https://docs-staging.nginx.com) sites, respectively. Ping the NGINX DocOps team in Slack if you need the password to these sites.
30+
1. In the GitHub UI, select the **Fork** button.
31+
32+
- On the **Create a new fork** page, select the **Owner** (the account where the fork of the repo will be placed).
33+
- Select the **Create fork** button.
34+
35+
2. If you plan to work on docs in your local development environment, clone your fork.
36+
For example, to clone the repo using SSH, you would run the following command:
37+
38+
```shell
39+
git clone git@github.com:<your-account>/nginx-gateway-fabric.git
40+
```
41+
42+
3. Check out a new feature branch in your fork. This is where you will work on your docs.
43+
44+
To do this via the command line, you would run the following command:
45+
46+
```shell
47+
git checkout -b <branch-name>
48+
```
49+
50+
**CAUTION**: Do not work on the main branch in your fork. This can cause issues when the NGINX Docs team needs to check out your feature branch for editing work.
51+
52+
4. Make atomic, [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) on your feature branch.
53+
54+
5. When ready, open a pull request into the **main** branch or a release branch in the **nginxinc/nginx-gateway-fabric** repo.
55+
56+
- Fill in [our pull request template](https://github.com/nginxinc/nginx-gateway-fabric/blob/main/.github/PULL_REQUEST_TEMPLATE.md) when opening your PR.
57+
- Tag the appropriate reviewers for your subject area.
58+
Technical reviewers should be able to verify that the information provided is accurate.
59+
Documentation reviewers ensure that the content conforms to the NGINX Style Guide, is grammatically correct, and adheres to the NGINX content templates.
60+
61+
## Release Management and Publishing
62+
63+
**`Main`** is the default branch in this repo. Main should always be releaseable.
64+
**Do not merge any content into main that is not approved for release.**
65+
66+
If you are working on content that isn't for a specific release (i.e., it can be published upon completion), open your pull request into the `main` branch.
67+
68+
### Prepare Content for Future Releases
69+
70+
If you are working on content for a future release, create a release branch from `main` that uses the naming format *ngf-release-x.y.x* (for example, `ngf-release-4.0.0`). Work on your docs in feature branches off of the release branch. Open pull requests into the release branch when you are ready to merge your work.
2471
2572
## Setup
2673

0 commit comments

Comments
 (0)