search

NOAA-RDHPCS / noaa-rdhpcs.github.io

NOAA RDHPCS documentation
https://docs.rdhpcs.noaa.gov/
Creative Commons Zero v1.0 Universal
1 stars 9 forks source link

Workflow for contributing to documentation #82

Open elisabethpatterson opened 5 months ago

elisabethpatterson commented 5 months ago

The following is a workflow for making a contribution to the documentation repository.

  1. Open an issue in the NOAA-RDHPCS/noaa-rdhpcs.github.io repository. The issue should describe the issue with the documentation, the desired change, etc.
  2. Fork and clone, or just clone the repository. The choice depends on whether the person making the change is a member of the NOAA-RDHPCS GitHub organization or not: a. If a member: Clone the repository (git clone git@github.com:NOAA-RDHPCS/noaa-rdhpcs.github.io.git). b. If not a member: Use the "fork and pull request" workflow: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests
  3. Create a new git branch in the local clone. The name of the branch doesn't matter, but it should be enough to indicate what is being done. Generic names (e.g., "updates", "fixes", etc.) do not help the developer or the reviewer recognize what is included. (git checkout -b new.branch.name).
  4. Modify the documentation. As mentioned previously, and as a good best-practice, only include one set of changes in each branch. That is, do not update multiple pages with new, unrelated text.
  5. Commit the change. The commit message should describe what is changed, why, etc. (see https://cbea.ms/git-commit/). The standard is to use at least two lines. The first line is a subject line, somewhat terse but descriptive (e.g., "Add scp transfer to data page"). The other line(s) should be more specific about what changes (e.g., added info for uses to scp data to the external DTNs).
  6. Push the branch. Where will determine if a member of the organization or not, but is typically: git push origin new.branch.name
  7. Open a pull request (PR) in NOAA-RDHPCS/noaa-rdhpcs.github.io. Add any additional information the reviewer(s) will need in the PR description. If the PR is tied to any issues, mention the issues using the #. You can even use keywords (https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests) to perform other automated workflow items (e.g., automatically close issues).
  8. Work with the reviewers to refine the update as needed. This will typically be to help refine the text (to make it easier to understand or flow better) or the layout. They may also request changes to allow the automated testing to pass (we have several CI tests to ensure the loose standard we have in https://github.com/NOAA-RDHPCS/noaa-rdhpcs.github.io/blob/main/CODE_STYLE.md are followed).
chanwilson commented 4 months ago

This workflow along with the training video recorded needs to be made available as part of our deployment.