Skip to content

feat: Move and update process documentation #717

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
# Contributing guidelines

The following is a set of guidelines for community contributions to this
project. We really appreciate your desire to contribute!
The following is a set of guidelines for community contributions to this project.

If you are an F5 employee, see the following additional guidance [For F5 Employees](./F5-NGINX-team-notes.md).
We really appreciate your desire to contribute!

If you are an F5 employee, see the following additional guidance on [Maintainers etiquette](/documentation/maintainers-etiquette.md).

## Table of contents

Expand All @@ -12,8 +13,8 @@ If you are an F5 employee, see the following additional guidance [For F5 Employe
- [Open a Discussion](#open-a-discussion)
- [Submit a Pull Request](#submit-a-pull-request)
- Review our [Git style guide](#git-style-guide)
- Review our Documentation [style guide](./templates/style-guide.md)
- Review our [Contributing guidelines for writers](./CONTRIBUTING_DOCS.md)
- Review the [Writing style guide](/documentation/style-guide.md)
- Review [Managing content with Hugo](/documentation/writing-hugo.md)
- [Issue Lifecycle](#issue-lifecycle)
- [Additional NGINX documentation](#additional-nginx-documentation)
- [F5 Contributor License Agreement (CLA)](#f5-contributor-license-agreement)
Expand Down Expand Up @@ -51,6 +52,7 @@ 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
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since we squash and merge I think this guideline is somewhat moot, but partially why conventional commits are important. I have stronger opinions about this and would like the git style guide to be its own document, but it will be its own 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:

Expand Down
6 changes: 5 additions & 1 deletion documentation/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

This directory contains the documentation for the NGINX Documentation repository.

It's used by the DocOps team to record how we configure our tools and instructions for certain precise tasks.
It's used by the DocOps team to record how we use our tools and instructions for common tasks.

There's also documentation around our ways of working, and ideas of significance wider than the scope of an issue or pull request.

Expand All @@ -12,4 +12,8 @@ If you're interested in contributing to the [NGINX documentation website](https:

## Topics

- [Contributing closed content](/documentation/closed-contributions.md)
- [Maintainers etiquette](/documentation/maintainers-etiquette.md)
- [Managing content with Hugo](/documentation/writing-hugo.md)
- [Proposals](/documentation/proposals/README.md)
- [Writing style guide](/documentation/style-guide.md)
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Contributing guidelines for closed content
# Contributing closed content

This document describes the process for authoring "closed content", which is content of a sensitive nature that cannot be publicised before release.

Expand Down
Original file line number Diff line number Diff line change
@@ -1,24 +1,21 @@
# For F5/NGINX Employees
# Maintainers etiquette

This repository is public, and we do as much of our work as possible in the public as a commitment to open source.

Before new content is published at https://docs.nginx.com, it must be committed to this `documentation` repository.

If you are an F5 employee unable to assign yourself as an owner of an issue or a reviewer of a pull request, ask a member of the NGINX documentation team for help.

If your content cannot be publicized before release, it is handled differently: read the [Contributing guidelines for closed content](/CLOSED_CONTRIBUTIONS.md) document.
This document is intended for the maintainers of the repository, who are any F5/NGINX employees that contribute to it.

We encourage you to work with community contributors. If you participate in PRs, issues, discussions, and more, follow these guidelines:

- Follow the [Code of Conduct](./CODE_OF_CONDUCT.md).
- Be helpful. We want to encourage people who contribute to continue.
- If you need to say "no," here's [an example](https://github.com/nginx/documentation/pull/307#issuecomment-2748521932) of how we interact with the community.
- If you need to say "no," here's [an example](https://github.com/nginx/documentation/pull/307#issuecomment-2748521932) of how to interact with the community.
- Avoid references and links to internal content.
- Do not include information about future releases, changes, or features, unless
specifically authorized.
- Do not include anything that even resembles PII.
- Do not include information about future releases, changes, or features, unless specifically authorized.
- Do not include anything that resembles PII.
- Do not include information that is proprietary to and/or private within F5/NGINX.

This repository is public, and we do as much of our work as possible in the public as a commitment to open source.

As an F5/NGINX employee, if you have a GitHub account, you should be able to clone these repositories.

If your content cannot be visible before release, you should read the [Contributing guidelines for closed content](/CLOSED_CONTRIBUTIONS.md) document.

To protect F5/NGINX, the ability to merge pull requests is strictly limited to employees of F5/NGINX.
File renamed without changes.
4 changes: 2 additions & 2 deletions CONTRIBUTING_DOCS.md → documentation/writing-hugo.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# Contributing guidelines for writers
# Managing content with Hugo

This page describes our guidelines on using [Hugo](https://gohugo.io/) to write documentation.

You will need [git](https://git-scm.com/) to interact with the repository and files: the content itself is written in Markdown.

Our workflow is to develop content locally, then submit a pull request once we've done our initial draft and editing passes.

If you're an employee of F5/NGINX, also read [For F5/NGINX Employees](./F5-NGINX-team-notes.md).
For guidance around how to write content, please check [the style guide](/documentation/style-guide.md).

## Setup

Expand Down