You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+88-27
Original file line number
Diff line number
Diff line change
@@ -2,47 +2,108 @@
2
2
3
3
The following is a set of guidelines for contributing to this project. We really appreciate that you are considering contributing!
4
4
5
-
#### Table Of Contents
6
5
7
-
[Getting Started](#getting-started)
6
+
## Getting Started
8
7
9
-
[Contributing](#contributing)
8
+
Follow our [Getting Started Guide](https://github.com/nginxinc/docs/blob/main/README.md#Getting-Started) to get this project up and running.
10
9
11
-
[Code Guidelines](#code-guidelines)
10
+
## Local Docs Development
12
11
13
-
[Code of Conduct](https://github.com/nginxinc/docs/blob/main/CODE_OF_CONDUCT.md)
12
+
To build the docs locally, run the desired `make` command from the docs directory:
14
13
15
-
## Getting Started
14
+
```text
15
+
make docs - runs a local hugo server so you can view docs in your browser while you work
16
+
make hugo-mod - cleans the Hugo module cache and fetches the latest version of the theme module
17
+
make docs-drafts - runs the local hugo server and includes all docs marked with `draft: true`
18
+
make clean - removes the local `public` directory, which is the default output path used by Hugo
19
+
```
16
20
17
-
Follow our [Getting Started Guide](https://github.com/nginxinc/docs/blob/main/README.md#Getting-Started) to get this project up and running.
21
+
## Add new docs
22
+
23
+
### Generate a new doc file using Hugo
24
+
25
+
To create a new doc file that contains all of the pre-configured Hugo front-matter and the docs task template, run the following command:
26
+
27
+
`hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>`
28
+
29
+
e.g.,
30
+
31
+
`hugo new getting-started/install.md`
32
+
33
+
The default template -- task -- should be used for most docs. To create docs using the other content templates, you can use the `--kind` flag:
34
+
35
+
`hugo new tutorials/deploy.md --kind tutorial`
36
+
37
+
The available content types (`kind`) are:
38
+
39
+
- concept: Helps a customer learn about a specific feature or feature set.
40
+
- tutorial: Walks a customer through an example use case scenario; results in a functional PoC environment.
41
+
- reference: Describes an API, command line tool, config options, etc.; should be generated automatically from source code.
42
+
- troubleshooting: Helps a customer solve a specific problem.
43
+
- openapi: Contains front-matter and shortcode for rendering an openapi.yaml spec.
44
+
45
+
## How to format docs
46
+
47
+
### How to format internal links
48
+
49
+
Format links as [Hugo refs](https://gohugo.io/content-management/cross-references/).
50
+
51
+
- File extensions are optional.
52
+
- You can use relative paths or just the filename. (**Paths without a leading / are first resolved relative to the current page, then to the remainder of the site.**)
53
+
- Anchors are supported.
54
+
55
+
For example:
56
+
57
+
```md
58
+
To install <product>, refer to the [installation instructions]({{< ref "install" >}}).
59
+
```
60
+
61
+
### How to use Hugo shortcodes
62
+
63
+
You can use [Hugo shortcodes](/docs/themes/f5-hugo/layouts/shortcodes/) to do things like format callouts, add images, and reuse content across different docs.
64
+
65
+
For example, to use the note callout:
66
+
67
+
```md
68
+
{{< note >}}Provide the text of the note here. {{< /note >}}
69
+
```
18
70
19
-
<!-- ### Project Structure (OPTIONAL) -->
71
+
The callout shortcodes also support multi-line blocks:
20
72
21
-
## Contributing
73
+
```md
74
+
{{< caution >}}
75
+
You should probably never do this specific thing in a production environment.
22
76
23
-
### Report a Bug
77
+
If you do, and things break, don't say we didn't warn you.
78
+
{{< /caution >}}
79
+
```
24
80
25
-
To report a bug, open an issue on GitHub with the label `bug` using the available bug report issue template. Please ensure the bug has not already been reported. **If the bug is a potential security vulnerability, please report it using our [security policy](https://github.com/nginxinc/docs/blob/main/SECURITY.md).**
81
+
Supported callouts:
26
82
27
-
### Suggest a Feature or Enhancement
83
+
-`caution`
84
+
-`important`
85
+
-`note`
86
+
-`see-also`
87
+
-`tip`
88
+
-`warning`
28
89
29
-
To suggest a feature or enhancement, please create an issue on GitHub with the label `enhancement` using the available [feature request template](https://github.com/nginxinc/docs/blob/main/.github/feature_request_template.md). Please ensure the feature or enhancement has not already been suggested.
90
+
A few more fun shortcodes:
30
91
31
-
### Open a Pull Request
92
+
-`fa`: inserts a Font Awesome icon
93
+
-`img`: include an image and define things like alt text and dimensions
94
+
-`include`: include the content of a file in another file (requires the included file to be in the content/includes directory; will be deprecated in favor of readfile)
95
+
-`link`: makes it possible to link to a file and prepend the path with the Hugo baseUrl
96
+
-`openapi`: loads an OpenAPI spec and renders as HTML using ReDoc
97
+
-`raw-html`: makes it possible to include a block of raw HTML
98
+
-`readfile`: includes the content of another file in the current file (intended to replace `include`)
99
+
-`bootstrap-table`: formats a table using Bootstrap classes; accepts any bootstrap table classes as additional arguments, e.g. `{{< bootstrap-table "table-bordered table-hover" }}`
32
100
33
-
- Fork the repo, create a branch, implement your changes, add any relevant tests, submit a PR when your changes are **tested** and ready for review.
34
-
- Fill in [our pull request template](https://github.com/nginxinc/docs/blob/main/.github/pull_request_template.md).
101
+
## Linting
35
102
36
-
Note: if you'd like to request or contribute new content, please consider creating a [feature request issue](https://github.com/nginxinc/docs/blob/main/.github/feature_request_template.md) first to start a discussion about the proposed content.
103
+
To run the markdownlint check, run the following command from the docs directory:
37
104
38
-
### Git Guidelines
105
+
```bash
106
+
markdownlint -c docs/mdlint_conf.json content
107
+
```
39
108
40
-
- Keep a clean, concise and meaningful git commit history on your branch (within reason), rebasing locally and squashing before submitting a PR.
41
-
- If possible and/or relevant, 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
42
-
- 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:
43
-
- In the subject line, use the present tense ("Add feature" not "Added feature").
44
-
- In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to...").
45
-
- Limit the subject line to 72 characters or less.
46
-
- Reference issues and pull requests liberally after the subject line.
47
-
- 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`).
48
-
109
+
> Note: You can run this tool on an entire directory or on an individual file.
Copy file name to clipboardExpand all lines: README.md
+33-91
Original file line number
Diff line number
Diff line change
@@ -17,115 +17,57 @@ Docs are written in Markdown. We build the docs using [Hugo](https://gohugo.io)
17
17
npm install -g markdownlint-cli
18
18
```
19
19
20
-
---
21
-
22
-
## 📨 Feature Requests, Support and Issue Reporting
23
-
24
-
For now, open an [issue](https://github.com/nginxinc/docs/issues).
25
-
26
-
## Local Docs Development
27
-
28
-
To build the docs locally, run the desired `make`command from the docs directory:
29
-
30
-
```text
31
-
make clean - removes the local`public` directory, which is the
32
-
default output path used by Hugo
33
-
make docs - runs a local hugo server so you can view docs in your
34
-
browser while you work
35
-
make hugo-mod - cleans the Hugo module cache and fetches the latest
36
-
version of the theme module
37
-
make docs-local - runs the `hugo`command to generate static HTML files
38
-
into the `public` directory
39
-
make docs-drafts - runs the local hugo server and includes all docs marked
40
-
with `draft: true`
41
-
```
42
-
43
-
## Linting
44
-
45
-
- To run the markdownlint check, run the following command from the docs directory:
46
-
47
-
```bash
48
-
markdownlint -c docs/mdlint_conf.json content
49
-
```
50
-
51
-
Note: You can run this tool on an entire directory or on an individual file.
52
-
53
-
## Add new docs
54
-
55
-
### Generate a new doc file using Hugo
56
-
57
-
To create a new doc file that contains all of the pre-configured Hugo front-matter and the docs task template, **run the following commandin the docs directory**:
58
-
59
-
`hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>`
20
+
Refer to the [CONTRIBUTING](./CONTRIBUTING.md) doc to learn how to develop content in this repo.
60
21
61
-
e.g.,
62
-
63
-
`hugo new getting-started/install.md`
64
-
65
-
The default template -- task -- should be used for most docs. To docs from the other content templates, you can use the `--kind` flag:
| All commits to the `dev` branch, feature branches, pull request deploy previews publish to the docs-dev site. <br>This site is primarily used for review of content under development. | All commits to `main` publish to the docs-staging environment automatically.<br>This is helpful for sharing staged content with stakeholders for signoff immediately prior to a release. | Content publishes to the production site once a day, via a GitHub Action. Members of the @nginxinc/nginx-docs team can manually trigger production deploys by running the GitHub Action or via Netlify Admin console. |
70
30
71
-
- concept: Helps a customer learn about a specific feature or feature set.
72
-
- tutorial: Walks a customer through an example use case scenario; results in a functional PoC environment.
73
-
- reference: Describes an API, command line tool, config options, etc.; should be generated automatically from source code.
74
-
- troubleshooting: Helps a customer solve a specific problem.
75
-
- openapi: Contains front-matter and shortcode for rendering an openapi.yaml spec
31
+
> NOTE: The dev and staging sites are password-protected; contact a member of the @nginxinc/nginx-docs team if you need access.
76
32
77
-
## How to format docs
33
+
---
78
34
79
-
### How to format internal links
35
+
## Git Guidelines
80
36
81
-
Format links as [Hugo refs](https://gohugo.io/content-management/cross-references/).
37
+
- Keep a clean, concise and meaningful git commit history on your branch (within reason), rebasing locally and squashing before submitting a PR.
38
+
- If possible and/or relevant, 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
39
+
- 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:
40
+
- In the subject line, use the present tense ("Add feature" not "Added feature").
41
+
- In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to...").
42
+
- Limit the subject line to 72 characters or less.
43
+
- Reference issues and pull requests liberally after the subject line.
44
+
- Add more detailed description in the body of the git message (`git commit -a` to give you more space and timein your text editor to write a good message instead of `git commit -am`).
82
45
83
-
- File extensions are optional.
84
-
- You can use relative paths or just the filename. (**Paths without a leading / are first resolved relative to the current page, then to the remainder of the site.**)
85
-
- Anchors are supported.
46
+
### Pull Requests
86
47
87
-
For example:
48
+
- Fork the repo, create a branch, implement your changes, add any relevant tests, and submit a PR when your changes are **tested** and ready for review.
49
+
- Fill in [our pull request template](https://github.com/nginxinc/docs/blob/main/.github/pull_request_template.md).
88
50
89
-
```md
90
-
To install <product>, refer to the [installation instructions]({{< ref "install">}}).
91
-
```
51
+
> Note: if you'd like to request or contribute new content, please consider creating a [feature request issue](https://github.com/nginxinc/docs/blob/main/.github/feature_request_template.md) first to start a discussion about the proposed content.
92
52
93
-
### How to use Hugo shortcodes
53
+
## Release Management and Publishing
94
54
95
-
You can use [Hugo shortcodes](/docs/themes/f5-hugo/layouts/shortcodes/) to do things like format callouts, add images, and reuse content across different docs.
55
+
**`Main`** is the default branch in this repo. Main should always be releaseable.
56
+
**Do not merge any content into main that is not approved for release.**
96
57
97
-
For example, to use the note callout:
58
+
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.
98
59
99
-
```md
100
-
{{< note >}}Provide the text of the note here. {{< /note >}}
101
-
```
60
+
### Prepare Content for Future Releases
102
61
103
-
The callout shortcodes also support multi-line blocks:
62
+
If you are working on content fora future release, create a release branch from `main` that uses the naming format *acronym-release-x.y.x* (for example, `adm-release-4.0.0`). Work on your docsin feature branches off of the release branch. Open pull requests into the release branch when you are ready to merge your work.
104
63
105
-
```md
106
-
{{< caution >}}
107
-
You should probably never do this specific thing in a production environment.
64
+
## 📨 Feature Requests, Support and Issue Reporting
108
65
109
-
If you do, and things break, don't say we didn't warn you.
110
-
{{< /caution >}}
111
-
```
66
+
### Report a Bug
112
67
113
-
Supported callouts:
68
+
To report a bug, open an issue on GitHub with the label `bug` using the available bug report issue template. Please ensure the bug has not already been reported. **If the bug is a potential security vulnerability, please report it using our [security policy](https://github.com/nginxinc/docs/blob/main/SECURITY.md).**
114
69
115
-
- `caution`
116
-
- `important`
117
-
- `note`
118
-
- `see-also`
119
-
- `tip`
120
-
- `warning`
70
+
### Suggest a Feature or Enhancement
121
71
122
-
A few more fun shortcodes:
72
+
To suggest a feature or enhancement, please create an issue on GitHub with the label `enhancement` using the available [feature request template](https://github.com/nginxinc/docs/blob/main/.github/feature_request_template.md). Please ensure the feature or enhancement has not already been suggested.
123
73
124
-
- `fa`: inserts a Font Awesome icon
125
-
- `img`: include an image and define things like alt text and dimensions
126
-
- `include`: include the content of a file in another file (requires the included file to be in the content/includes directory; will be deprecated in favor of readfile)
127
-
- `link`: makes it possible to link to a file and prepend the path with the Hugo baseUrl
128
-
- `openapi`: loads an OpenAPI spec and renders as HTML using ReDoc
129
-
- `raw-html`: makes it possible to include a block of raw HTML
130
-
- `readfile`: includes the content of another file in the current file (intended to replace `include`)
131
-
- `bootstrap-table`: formats a table using Bootstrap classes; accepts any bootstrap table classes as additional arguments, e.g. `{{< bootstrap-table "table-bordered table-hover" }}`
0 commit comments