From aa297ce7450e5c623f9342c9a175aafeeb2addea Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 20 Jun 2025 15:12:06 +0100 Subject: [PATCH] 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. --- CONTRIBUTING.md | 12 ++++++----- documentation/README.md | 6 +++++- .../closed-contributions.md | 2 +- .../maintainers-etiquette.md | 21 ++++++++----------- {templates => documentation}/style-guide.md | 0 .../writing-hugo.md | 4 ++-- 6 files changed, 24 insertions(+), 21 deletions(-) rename CLOSED_CONTRIBUTIONS.md => documentation/closed-contributions.md (98%) rename F5-NGINX-team-notes.md => documentation/maintainers-etiquette.md (60%) rename {templates => documentation}/style-guide.md (100%) rename CONTRIBUTING_DOCS.md => documentation/writing-hugo.md (98%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1c3f94a48..01c0637ec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 @@ -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) @@ -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 +- 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 and summarized in the next few points: diff --git a/documentation/README.md b/documentation/README.md index 4783c0baf..af9a01392 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -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. @@ -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) diff --git a/CLOSED_CONTRIBUTIONS.md b/documentation/closed-contributions.md similarity index 98% rename from CLOSED_CONTRIBUTIONS.md rename to documentation/closed-contributions.md index e031c3a24..cc0970362 100644 --- a/CLOSED_CONTRIBUTIONS.md +++ b/documentation/closed-contributions.md @@ -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. diff --git a/F5-NGINX-team-notes.md b/documentation/maintainers-etiquette.md similarity index 60% rename from F5-NGINX-team-notes.md rename to documentation/maintainers-etiquette.md index 1ddfa64cf..8aae8a61b 100644 --- a/F5-NGINX-team-notes.md +++ b/documentation/maintainers-etiquette.md @@ -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. diff --git a/templates/style-guide.md b/documentation/style-guide.md similarity index 100% rename from templates/style-guide.md rename to documentation/style-guide.md diff --git a/CONTRIBUTING_DOCS.md b/documentation/writing-hugo.md similarity index 98% rename from CONTRIBUTING_DOCS.md rename to documentation/writing-hugo.md index 3fa8270f3..20587fafe 100644 --- a/CONTRIBUTING_DOCS.md +++ b/documentation/writing-hugo.md @@ -1,4 +1,4 @@ -# Contributing guidelines for writers +# Managing content with Hugo This page describes our guidelines on using [Hugo](https://gohugo.io/) to write documentation. @@ -6,7 +6,7 @@ You will need [git](https://git-scm.com/) to interact with the repository and fi 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