Updates per F5 Open Source Contribution Policy

mjang · mjang · commit b63e9e98431e · 2024-10-11T10:28:22.000-07:00
diff --git a/.github/workflows/f5-cla.yml b/.github/workflows/f5-cla.yml
@@ -17,7 +17,7 @@ jobs:
     steps:
       - name: Run F5 Contributor License Agreement (CLA) assistant
         if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have hereby read the F5 CLA and agree to its terms') || github.event_name == 'pull_request_target'
-        uses: contributor-assistant/github-action@f41946747f85d28e9a738f4f38dbcc74b69c7e0e # v2.5.1
+        uses: contributor-assistant/github-action@9340315624c6e16cef1f2c63bdeb0f0c49c6f474 # v2.4.0
         with:
           # Any pull request targeting the following branch will trigger a CLA check.
           # NOTE: You might need to edit this value to 'main'.
diff --git a/.github/workflows/ossf_scorecard.yml b/.github/workflows/ossf_scorecard.yml
@@ -56,6 +56,6 @@ jobs:
 
       # Upload the results to GitHub's code scanning dashboard.
       - name: Upload SARIF results to code scanning
-        uses: github/codeql-action/upload-sarif@2c779ab0d087cd7fe7b826087247c2c81f27bfa6 # v3.26.5
+        uses: github/codeql-action/upload-sarif@eb055d739abdc2e8de2e5f4ba1a8b246daa779aa # v3.26.0
         with:
           sarif_file: results.sarif
diff --git a/.github/workflows/rename_template.yml b/.github/workflows/rename_template.yml
@@ -0,0 +1,38 @@
+---
+name: Rename the template
+on:
+  push:
+permissions: read-all
+jobs:
+  rename-template:
+    name: Replace the templated variables in the repository with the newly created repository details
+    if: ${{ !contains(github.repository, 'template') }}
+    runs-on: ubuntu-22.04
+    permissions:
+      contents: write
+    steps:
+      - name: Check out the codebase
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+
+      - name: Set $REPOSITORY_NAME
+        run: echo "REPOSITORY_NAME=$(echo '${{ github.repository }}' | awk -F '/' '{print $2}' | tr '-' '_' | tr '[:upper:]' '[:lower:]')" >> $GITHUB_ENV
+        shell: bash
+
+      - name: Set $REPOSITORY_URL
+        run: echo "REPOSITORY_URL=$(echo '${{ github.repository }}' | awk -F '/' '{print $2}')" >> $GITHUB_ENV
+        shell: bash
+
+      - name: Set $REPOSITORY_OWNER
+        run: echo "REPOSITORY_OWNER=$(echo '${{ github.repository }}' | awk -F '/' '{print $1}')" >> $GITHUB_ENV
+        shell: bash
+
+      - name: Rename the project
+        run: |
+          echo "Renaming the project with -a(author) ${{ env.REPOSITORY_OWNER }} -n(name) ${{ env.REPOSITORY_NAME }} -u(urlname) ${{ env.REPOSITORY_URL }}"
+          .github/workflows/scripts/rename_project.sh -a ${{ env.REPOSITORY_OWNER }} -n ${{ env.REPOSITORY_NAME }} -u ${{ env.REPOSITORY_URL }}
+
+      - name: Commit and push changes
+        uses: stefanzweifel/git-auto-commit-action@8621497c8c39c72f3e2a999a26b4ca1b5058a842 # v5.0.1
+        with:
+          commit_message: "✅ Ready to clone and code."
+          push_options: --force
diff --git a/.github/workflows/scripts/rename_project.sh b/.github/workflows/scripts/rename_project.sh
@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# vim:sw=2:ts=2:sts=2:et
+while getopts a:n:u: flag
+do
+  case "${flag}" in
+    a) owner=${OPTARG};;
+    n) name=${OPTARG};;
+    u) url=${OPTARG};;
+    *) echo "Invalid flag: ${flag}"; exit 1;;
+  esac
+done
+
+echo "Owner: $owner";
+echo "Repository Name: $name";
+echo "Repository URL: $url";
+
+echo "Renaming repository..."
+
+original_owner="{{REPOSITORY_OWNER}}"
+original_name="{{REPOSITORY_NAME}}"
+original_url="{{REPOSITORY_URL}}"
+for filename in $(git ls-files)
+do
+  sed -i "s/$original_owner/$owner/g" "$filename"
+  sed -i "s/$original_name/$name/g" "$filename"
+  sed -i "s/$original_url/$url/g" "$filename"
+  echo "Renamed $filename"
+done
+
+# This command runs only once on GitHub Actions!
+rm -f .github/workflows/rename_template.yml
+rm -rf .github/workflows/scripts
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,14 +1,50 @@
-# Contributing guidelines
+# Contributing Guidelines
 
-The following is a set of guidelines for contributing to this project. We really appreciate your desire to contribute!
+The following is a set of guidelines for contributing to this project.
+We really appreciate your desire to contribute!
 
-## F5 Contributor License Agreement (CLA)
+## Table of Contents
 
-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.
+- [Ask a Question](#ask-a-question)
+- [Report a Bug](#report-a-bug)
+- [Suggest a Feature or Enhancement](#suggest-a-feature-or-enhancement)
+- [Open a Discussion](#open-a-discussion)
+- [Submit a Pull Request](#submit-a-pull-request)
+- [Issue Lifecycle](#issue-lifecycle)
+- [F5 Contributor License Agreement (CLA)](#f5-contributor-license-agreement)
 
-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 Pull or Merge Requests.
+## Ask a Question
+
+To ask a question, open an issue on GitHub with the label `question`.
+
+## Report a Bug
+
+To report a bug, open an issue on GitHub with the label `bug` using the
+available bug report issue template. Before reporting a bug, make sure the
+issue has not already been reported.
+
+## Suggest a Feature or Enhancement
+
+To suggest a feature or enhancement, open an issue on GitHub with the label
+`feature` or `enhancement` using the available feature request issue template.
+Please ensure the feature or enhancement has not already been suggested.
+
+## Open a Discussion
+
+If you want to start a conversation with the community and maintainers,
+we encourage you to use
+[GitHub Discussions](https://github.com/nginxinc/oss-docs/discussions).
+
+## Submit a Pull Request
 
-## Options to get started
+To contribute to NGINX documentation, follow these steps:
+
+- Fork the NGINX repository
+- Create a branch
+- Implement your changes in your branch
+- Submit a pull request (PR) when your changes are ready for review
+
+## Contributing with Git
 
 <!-- Separate doc pages, CONTRIBUTING_GIT.md and CONTRIBUTING_other.md. 
 Need: issue to include "Edit this page" links, similar to what we already do for N Unit docs, https://unit.nginx.org/ -->
@@ -19,5 +55,21 @@ At this time, we support contributions using Git. We expect this audience to als
 We're working on alternative contribution methods, described in CONTRIBUTING_OTHER.md
 -->
 
-Alternatively, you're welcome to highight problems with our documentation as
+Alternatively, you're welcome to highlight problems with our documentation as
 described in our [support](./SUPPORT.md) page.
+
+## Issue Lifecycle
+
+To ensure a balance between work carried out by the NGINX team while encouraging community involvement on this project, we use the following
+issue lifecycle:
+
+- A new issue is created by a community member
+- An owner on the NGINX team is assigned to the issue; this owner shepherds the issue through the subsequent stages in the issue lifecycle
+- The owner assigns one or more [labels](https://github.com/nginxinc/oss-docs/issues/labels) to the issue
+- The owner, in collaboration with the wider team, determines what milestone to attach to an issue. They may be milestones correspond to product releases
+
+## F5 Contributor License Agreement
+
+F5 requires all external contributors to agree to the terms of the [F5 CLA](./CLA/cla-markdown.md), before any of their changes can be incorporated into an F5 Open Source repository.
+
+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 Pull or Merge Requests.
diff --git a/CONTRIBUTING_GIT.md b/CONTRIBUTING_GIT.md
@@ -1,12 +1,21 @@
 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.
 
 Once you add and/or edit our Markdown source files, you can build the content locally as described on this page.
+Before you [Submit a Pull Request](#submit-a-pull-request), we recommend that you first:
 
-## Static Site Generator (Hugo)
+- Set up our [Static site generator](#static-site-generator)
+- Review how to [Include images](#include-images)
+- Review our [Git style guide](#git-style-guide)
+- Learn how to [Build documentation locally](#build-documentation-locally)
 
-We build our documentation with the [Hugo](https://gohugo.io/) static site generator. 
+## Static Site Generator
 
-## Images
+You will need to install Hugo to build and preview docs in your local development environment.
+Refer to the [Hugo installation instructions](https://gohugo.io/getting-started/installing/) for more information.
+
+**NOTE**: We are currently running [Hugo v0.134.2](https://github.com/gohugoio/hugo/releases/tag/v0.134.2) in production.
+
+## Include images
 
 When you set up an image, this is the standard format:
 
@@ -19,16 +28,28 @@ Refer to the [Hugo installation instructions](https://gohugo.io/getting-started/
 
 **NOTE**: We are currently running [Hugo v0.115.3](https://github.com/gohugoio/hugo/releases/tag/v0.115.3) in production. If you run a different version of Hugo (older or newer), you might see unexpected errors.
 
-### Local docs development
+## Submit a Pull Request
+
+Follow this plan to contribute a change to NGINX source code:
+
+- Fork the NGINX repository
+- Create a branch
+- Implement your changes in this branch
+- Submit a pull request (PR) when your changes are tested and ready for review
 
-To build the docs locally, run the desired `make` command from the docs directory:
+### Git Style Guide
 
-```text
-make docs           -   runs a local Hugo server so you can view docs in your browser while you work
-make hugo-mod       -   cleans the Hugo module cache and fetches the latest version of the theme module
-make docs-drafts    -   runs the local Hugo server and includes all docs marked with `draft: true`
-make clean          -   removes the local `public` directory, which is the default output path used by Hugo
-```
+- Keep a clean, concise and meaningful git commit history on your branch, rebasing locally and squashing before
+  submitting a PR
+- 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:
+
+  - In the subject line, use the present tense ("Add feature" not "Added feature")
+  - In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to...")
+  - Limit the subject line to 72 characters or less
+  - Reference issues and pull requests liberally after the subject line
+  - 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`)
 
 ### Add new docs
 <!--
@@ -52,11 +73,3 @@ Consistent with the [Diataxis](https://diataxis.fr) framework, our documentation
 - tutorial: Walks a customer through an example use case scenario; results in a functional PoC environment.
 - reference: Describes an API, command line tool, config options, etc.; should be generated automatically from source code. 
 - openapi: Contains front-matter and shortcode for rendering an openapi.yaml spec.
-
-### How to format docs
-
-#### How to format internal links
-
-Format links as [Hugo `refs`](https://gohugo.io/content-management/cross-references/). 
-
-- File extensions are optional.
diff --git a/SUPPORT.md b/SUPPORT.md
@@ -23,11 +23,9 @@ If you are not a member, click [here](https://community.nginx.org/joinslack) to
 
 Once you join, check out the `#beginner-questions` and `nginx-users` channels :) -->
 
-<!-- The dot org site has moved away from mailing lists, I think we should do the same.
-
 ### Mailing List
 
-Want to get in touch with the NGINX development team directly? Try using the relevant mailing list found at <https://mailman.nginx.org/mailman3/lists/>! -->
+Want to get in touch with the NGINX development team directly? Try using the relevant mailing list found at <https://mailman.nginx.org/mailman3/lists/>!
 
 ### Documentation
 
