Skip to content

Commit 7e3f972

Browse files
mjangmjang
authored
Merge pull request #1 from nginxinc/readme-updates
docs: Community READMEs (and more), iteration 1
2 parents d0ca7b7 + bee6087 commit 7e3f972

31 files changed

+3335
-283
lines changed

‎.github/CODEOWNERS

Lines changed: 31 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,31 @@
1-
# Main global owner #
2-
#####################
3-
*
1+
# Each of these groups of CODEOWNERS have approval and merge authority over
2+
# the noted directories.
3+
#
4+
# If you want to add, modify, or delete files in any of these directories,
5+
# open a pull request. Then add the appropriate group name (without the `@`)
6+
# to the list of "Reviewers."
7+
#
8+
# Order is important; the last matching pattern takes precedence.
9+
# For example, when someone opens a pull request that only modifies files
10+
# in the content/nginx-one directory, you should assign @nginxinc/one-docs-approvers
11+
# as a reviewer.
12+
#
13+
# Lines starting with '#' are comments.
14+
# Each line is a file pattern followed by one or more owners.
15+
16+
# DocOps
17+
* @nginxinc/nginx-docs
18+
# NGINX Plus
19+
content/nginx/* @nginxinc/plus-docs-approvers
20+
# NGINX Agent
21+
content/nginx/nms/agent/* @nginxinc/agent-docs-approvers
22+
# NGINX One
23+
content/nginx-one/* @nginxinc/one-docs-approvers
24+
# NGINX Instance Manager
25+
content/nms/nim/* @nginxinc/nim-docs-approvers
26+
content/nim/* @nginxinc/nim-docs-approvers
27+
# NGINX App Protect WAF
28+
content/nap-waf/* @nginxinc/nap-docs-approvers
29+
data/nap-waf/* @nginxinc/nap-docs-approvers
30+
# NGINX App Protect DoS
31+
content/nap-dos/* @nginxinc/dos-docs-approvers

‎CHANGELOG.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Changelog
22

3+
<!-- While we have a changelog for current docs at https://github.com/nginxinc/docs/blob/main/CHANGELOG.md, I'm not convinced -->
4+
35
## 1.0.0 (Month Date, Year)
46

5-
Initial release of the NGINX template repository.
7+
Initial open source release of the documentation repository for enterprise NGINX products. This is a filtered mirror of an internal repository.

‎CONTRIBUTING.md

Lines changed: 68 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,92 @@
1-
# Contributing Guidelines
1+
# Contributing guidelines
22

3-
The following is a set of guidelines for contributing to this project. We really appreciate that you are considering contributing!
3+
The following is a set of guidelines for community contributions to this
4+
project. We really appreciate your desire to contribute!
45

5-
#### Table Of Contents
6+
If you are an F5/NGINX employee, see the following guidance [For F5/NGINX Employees](./F5-NGINX-team-notes.md).
67

7-
[Getting Started](#getting-started)
8+
## Table of contents
89

9-
[Contributing](#contributing)
10+
- [Report a Bug](#report-a-bug)
11+
- [Suggest a Feature or Enhancement](#suggest-a-feature-or-enhancement)
12+
- [Open a Discussion](#open-a-discussion)
13+
- [Submit a Pull Request](#submit-a-pull-request)
14+
- Review our [Git style guide](#git-style-guide)
15+
- Review our Documentation [style guide](./templates/style-guide.md)
16+
- [Issue Lifecycle](#issue-lifecycle)
17+
- [Content edited elsewhere](#content-edited-elsewhere)
18+
- [F5 Contributor License Agreement (CLA)](#f5-contributor-license-agreement)
1019

11-
[Code Guidelines](#code-guidelines)
20+
## Report a bug
1221

13-
[Code of Conduct](/CODE_OF_CONDUCT.md)
22+
To report a bug, open an issue on GitHub with the label `bug` using the
23+
available bug report issue template. Before reporting a bug, make sure the
24+
issue has not already been reported.
1425

15-
## Getting Started
26+
## Suggest a feature or enhancement
1627

17-
Follow the instructions on the README's [Getting Started](/README.md#Getting-Started) section to get this project up and running.
28+
To suggest a feature or enhancement, open an issue on GitHub with the label
29+
`feature` or `enhancement` using the available feature request issue template.
30+
Please ensure the feature or enhancement has not already been suggested.
1831

19-
<!-- ### Project Structure (OPTIONAL) -->
32+
## Open a discussion
2033

21-
## Contributing
34+
If you want to start a conversation with the community and maintainers,
35+
we encourage you to use
36+
[GitHub Discussions](https://github.com/nginxinc/oss-docs/discussions).
2237

23-
### Report a Bug
38+
## Submit a Pull Request
2439

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](/SECURITY.md).**
40+
To contribute to F5 NGINX documentation, follow these steps:
2641

27-
### Suggest a Feature or Enhancement
42+
- Fork the NGINX repository
43+
- Create a branch
44+
- Implement your changes in your branch
45+
- Submit a pull request (PR) when your changes are ready for review
2846

29-
To suggest a feature or enhancement, please create an issue on GitHub with the label `enhancement` using the available [feature request template](/.github/feature_request_template.md). Please ensure the feature or enhancement has not already been suggested.
47+
Alternatively, you're welcome to suggest improvements to highlight problems with
48+
our documentation as described in our [support](./SUPPORT.md) page.
3049

31-
### Open a Pull Request (PR)
50+
### Git Style Guide
3251

33-
- 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.
34-
- Fill in the [PR template](/.github/pull_request_template.md).
52+
- Keep a clean, concise and meaningful Git commit history on your branch, rebasing locally and squashing before you submit a PR
53+
- Follow the guidelines of writing a good commit message as described here <https://chris.beams.io/posts/git-commit/>
54+
and summarized in the next few points:
3555

36-
**Note:** If you'd like to implement a new feature, please consider creating a [feature request issue](/.github/feature_request_template.md) first to start a discussion about the feature.
56+
- In the subject line, use the present tense ("Add feature" not "Added feature")
57+
- In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to...")
58+
- Limit the subject line to 72 characters or less
59+
- Reference issues and pull requests liberally after the subject line
60+
- Add more detailed description in the body of the git message (`git commit -a` to give you more space and time in
61+
your text editor to write a good message instead of `git commit -am`)
3762

38-
#### F5 Contributor License Agreement (CLA)
63+
### Documentation style guide
3964

40-
F5 requires all external contributors to agree to the terms of the F5 CLA (available [here](https://github.com/f5/.github/blob/main/CLA/cla-markdown.md)) before any of their changes can be incorporated into an F5 Open Source repository.
65+
For detailed guidance, see our documentation [style guide](./templates/style-guide.md).
4166

42-
If you have not yet agreed to the F5 CLA terms and submit a PR to this repository, a bot will prompt you to view and agree to the F5 CLA. You will have to agree to the F5 CLA terms through a comment in the PR before any of your changes can be merged. Your agreement signature will be safely stored by F5 and no longer be required in future PRs.
67+
## Issue lifecycle
68+
69+
To ensure a balance between work carried out by the NGINX team while encouraging community involvement on this project, we use the following
70+
issue lifecycle:
71+
72+
- A new issue is created by a community member
73+
- An owner on the NGINX team is assigned to the issue; this owner shepherds the issue through the subsequent stages in the issue lifecycle
74+
- The owner assigns one or more [labels](https://github.com/nginxinc/oss-docs/issues/labels) to the issue
75+
- The owner, in collaboration with the community member, determines what milestone to attach to an issue. They may be milestones correspond to product releases
76+
77+
## Content edited elsewhere
4378

44-
## Code Guidelines
79+
This repository does not include all documentation available at https://docs.nginx.com. Other relevant repositories include:
4580

46-
<!-- ### Go/Python/Bash/etc... Guidelines (OPTIONAL) -->
81+
- [NGINX Open Source](https://github.com/nginx/nginx)
82+
- [NGINX Unit](https://github.com/nginx/unit)
83+
- [NGINX Ingress Controller](https://github.com/nginxinc/kubernetes-ingress/)
84+
- [NGINX Gateway Fabric](https://github.com/nginxinc/nginx-gateway-fabric)
4785

48-
### Git Guidelines
86+
You can find documentation source code in the `docs` or `site` subdirectories.
4987

50-
- Keep a clean, concise and meaningful git commit history on your branch (within reason), rebasing locally and squashing before submitting a PR.
51-
- 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.
52-
- 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:
53-
- In the subject line, use the present tense ("Add feature" not "Added feature").
54-
- In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to...").
55-
- Limit the subject line to 72 characters or less.
56-
- Reference issues and pull requests liberally after the subject line.
57-
- 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`).
88+
## F5 Contributor License Agreement
89+
90+
F5 requires all external contributors to agree to the terms of the F5 CLA (available [here](https://github.com/f5/.github/blob/main/CLA/cla-markdown.md)) before any of their changes can be incorporated into an F5 Open Source repository.
91+
92+
If you have not yet agreed to the F5 CLA terms and submit a PR to this repository, a bot will prompt you to view and agree to the F5 CLA. You will have to agree to the F5 CLA terms through a comment in the PR before any of your changes can be merged. Your agreement signature will be safely stored by F5 and no longer be required in future PRs.

‎CONTRIBUTING_DOCS.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Contributing guidelines for experts
2+
3+
If you want to contribute, know Git, and can work from the command line, this page can help you. As noted in the [README](./README.md), we create source content for our documentation in Markdown.
4+
5+
Once you add and/or edit our Markdown source files, you can build the content locally as described on this page.
6+
Before you [Submit a Pull Request](#submit-a-pull-request), we recommend that you first:
7+
8+
- Set up our [Static site generator](#static-site-generator)
9+
- If you want to add images, review how to [Include images](#include-images)
10+
- Learn how to [Build documentation locally](#build-documentation-locally)
11+
12+
## Static site generator
13+
14+
You will need to install Hugo to build and preview docs in your local development environment.
15+
Refer to the [Hugo installation instructions](https://gohugo.io/getting-started/installing/) for more information.
16+
17+
**NOTE**: We are currently running [Hugo v0.134.2](https://github.com/gohugoio/hugo/releases/tag/v0.134.2) in production.
18+
19+
## Include images
20+
21+
When you set up an image, this is the standard format:
22+
23+
{{< img src="path/to/images/file-name.png" alt="descriptive text for screenreaders" >}}
24+
25+
You'll find images in the [static](../static) subdirectory, in a directory associated with the documentation. For example, if you've set up the `file-name.png`
26+
image, you should copy that file to the `static/path/to/images` directory.
27+
28+
## Build documentation locally
29+
30+
To build and preview docs in your local development environment, you need to install Hugo.
31+
Refer to the [Hugo installation instructions](https://gohugo.io/getting-started/installing/) for more information.
32+
33+
## Submit a Pull Request
34+
35+
Follow this plan to contribute a change to NGINX source code:
36+
37+
- Fork the NGINX repository
38+
- Create a branch
39+
- Implement your changes in this branch
40+
- Submit a pull request (PR) when your changes are tested and ready for review
41+
42+
### Add new docs
43+
44+
Consistent with the [Diataxis](https://diataxis.fr) framework, our documentation includes the following content types:
45+
46+
- concept: Helps a customer learn about a specific feature or feature set.
47+
- tutorial: Walks a customer through an example use case scenario; results in a functional PoC environment.
48+
- reference: Describes an API, command line tool, config options, etc.; should be generated automatically from source code.
49+
- openapi: Contains front-matter and shortcode for rendering an openapi.yaml spec.

‎F5-NGINX-team-notes.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# For F5/NGINX Employees
2+
3+
This repository is a functional mirror. If you want to make a change to F5/NGINX
4+
documentation, use the private source repository.
5+
6+
We encourage you to work with community contributors. If you participate in
7+
PRs, issues, discussions, and more, follow these guidelines:
8+
9+
- Follow the [Code of Conduct](./CODE_OF_CONDUCT.md).
10+
- Be helpful. We want to encourage people who contribute to continue.
11+
- Avoid references and links to internal content.
12+
- Do not include information about future releases, changes, or features, unless
13+
specifically authorized.
14+
- Do not include information that is proprietary to and/or private within F5/NGINX.

0 commit comments

Comments
 (0)