From 22e2a5607cdf03199b9c28790d61ded2c0dade12 Mon Sep 17 00:00:00 2001 From: sgoodman Date: Tue, 17 Aug 2021 09:16:35 +0300 Subject: [PATCH 1/3] contributing Added instructions on initial setup of local repo. --- README.md | 120 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 119 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 433596f..be623cd 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,120 @@ # publishing-tutorial-sample-repo -A sample repo to be used in conjunction with the tutorial "Getting started publishing with Pantheon 2" +A sample repo to be used in conjunction with the tutorial "Getting started publishing with Pantheon 2" + +[![Build Status](https://travis-ci.org/redhataccess/pantheon.png)](https://travis-ci.org/redhataccess/pantheon) +[![Code Coverage](https://codecov.io/gh/redhataccess/pantheon/branch/master/graph/badge.svg)](https://codecov.io/github/redhataccess/pantheon?branch=master) + +Pantheon 2 is a modular documentation management and publication system based on asciidoc +and built on top of Apache sling. +* [Contributing to Pantheon](#contributing-to-pantheon) +* [Installing Pantheon](#installing-pantheon) + * [Prerequisites](#prerequisites) + * [Environment Variables](#environment-variables) + * [Building the application](#building-the-application) + * [Unit tests](#unit-tests) + * [Running the application](#running-the-application) + * [Live deploy of code](#live-deploy-of-code) + * [Using the application](#using-the-application) + * [Other use cases](#other-use-cases) + * [Developing the frontend code](#developing-the-frontend-code) +* [End user documentation](#end-user-documentation) + +## Contributing to Pantheon + +### Filing a bug for Pantheon 2 end-user documentation + +If you have any suggestions to improve or extend the end-user documentation, create a new issue and tag @pantheon-doc-authors. + +### Prerequisites + +* You must have an account on GitHub. + [Signing up for a new GitHub account](https://help.github.com/en/github/getting-started-with-github/signing-up-for-a-new-github-account) +* You must have registered SSH keys in your GitHub account. +[Adding a new SSH key to your GitHub account](https://help.github.com/en/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account) +* You must be a member of the `pantheon-developers` or `pantheon-doc-authors` team in the `redhataccess` group in GitHub. +* You must be logged in to your account on GitHub. + +### Forking the repository + +Fork the repository so that you can create and work with branches independently of the `redhataccess/pantheon` repository. + +1. In a web browser, navigate to https://github.com/redhataccess/pantheon +1. Click **Fork**. +1. Click your user space in GitHub. + +### Cloning the repository + +After you have forked the repository, you must clone it to your local machine and add the original `redhataccess/pantheon` repository as an upstream remote. + +1. From a terminal, clone the repository: + + ```sh + $ git clone git@github.com:/pantheon.git + ``` +1. Set up `redhataccess/pantheon` as the upstream: + + ```sh + $ cd pantheon + $ git remote add upstream git@github.com:redhataccess/pantheon.git + ``` + +### Creating a working branch + +Whenever you work on a new issue, you must create a new working branch based on the latest version of the upstream master branch. + +1. Ensure you are on master + + ```sh + $ git checkout master + ``` +1. Ensure your fork is up to date + + ```sh + $ git pull upstream master + ``` +1. Create a working branch based on the issue in JIRA. For example: + + + ```sh + $ git checkout -b FCCEUD- + ``` + +### Creating a pull request and completing review + +When your work is ready to be reviewed and merged, create a pull request. + +1. Push your working branch to your fork: + + ```sh + $ git push -u origin + ``` +1. From the repository page in GitHub, click **New pull request**. +1. Select your working branch from the compare list. +1. Add `WIP:` to the title of the pull request. This automatically converts the pull request to a draft pull request. +1. Click **Create new pull request**. +1. Add the **awaiting tech review** label to the pull request. +1. In the pull request comment field, enter `@redhataccess/eud-tech-review Please review for technical completeness and accuracy`. + + +### The review process + +Both the technical review and peer review processes take place in pull requests in GitHub. + +#### Documentation review +After creating and labeling a pull request as outlined above, the developers review the pull request and add comments regarding technical accuracy. Writers receive a notification that comments have been added via email, and when all comments have been addressed, the developers change the label from **awaiting tech review** to **tech review complete**. + +When technical review is complete, writers click the **Reviewers** gear icon and select the name of a team member to request peer review. The peer writer reviews the pull request for clarity, consistency, and compliance with necessary standards. +Writers receive a notification that comments have been added via email, and when all comments have been addressed, the reviewer clicks **Review changes > Approve** from the **Files changed** tab of the pull request to approve the changes and the pull request. + +#### Code review + +For code pull requests, one or more developers review the pull request. A contributor submits a PR and uses Github's **Reviewers** gear icon to tag `@redhataccess/pantheon-developers`. A developer comments on the code, and discusses it with the submitter, before ultimately deciding to accept or reject the PR. + +### Merging a pull request + +When you have addressed all technical review and peer review comments, notify the developers to accept the pull request. + +1. Remove `WIP` from the title of the pull request. +1. Click **Request Review** and enter `@redhataccess/pantheon-developers`. + +The developers check that the **Tech review complete** label has been added to the pull request and peer pull request approval provided, then accept it. From 623542b58c27c3c5afd5ba1a0e26c2c065766558 Mon Sep 17 00:00:00 2001 From: sgoodman Date: Tue, 17 Aug 2021 15:00:23 +0300 Subject: [PATCH 2/3] contributing: More edits. --- README.md | 62 ++++++++++++++++++------------------------------------- 1 file changed, 20 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index be623cd..cf36116 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,13 @@ -# publishing-tutorial-sample-repo +# Publishing tutorial sample repo A sample repo to be used in conjunction with the tutorial "Getting started publishing with Pantheon 2" -[![Build Status](https://travis-ci.org/redhataccess/pantheon.png)](https://travis-ci.org/redhataccess/pantheon) -[![Code Coverage](https://codecov.io/gh/redhataccess/pantheon/branch/master/graph/badge.svg)](https://codecov.io/github/redhataccess/pantheon?branch=master) +* [Contributing to this repository](#contributing-to-this-repository) -Pantheon 2 is a modular documentation management and publication system based on asciidoc -and built on top of Apache sling. -* [Contributing to Pantheon](#contributing-to-pantheon) -* [Installing Pantheon](#installing-pantheon) - * [Prerequisites](#prerequisites) - * [Environment Variables](#environment-variables) - * [Building the application](#building-the-application) - * [Unit tests](#unit-tests) - * [Running the application](#running-the-application) - * [Live deploy of code](#live-deploy-of-code) - * [Using the application](#using-the-application) - * [Other use cases](#other-use-cases) - * [Developing the frontend code](#developing-the-frontend-code) -* [End user documentation](#end-user-documentation) +## Contributing to this repository -## Contributing to Pantheon +### Filing a bug -### Filing a bug for Pantheon 2 end-user documentation - -If you have any suggestions to improve or extend the end-user documentation, create a new issue and tag @pantheon-doc-authors. +If you have any suggestions to improve or extend this repository, add a new issue in the repository. ### Prerequisites @@ -38,45 +22,44 @@ If you have any suggestions to improve or extend the end-user documentation, cre Fork the repository so that you can create and work with branches independently of the `redhataccess/pantheon` repository. -1. In a web browser, navigate to https://github.com/redhataccess/pantheon +1. In a web browser, navigate to https://github.com/redhat-documentation/publishing-tutorial-sample-repo 1. Click **Fork**. 1. Click your user space in GitHub. ### Cloning the repository -After you have forked the repository, you must clone it to your local machine and add the original `redhataccess/pantheon` repository as an upstream remote. +After you have forked the repository, you must clone it to your local machine and add the original `redhat-documentation/publishing-tutorial-sample-repo` repository as an upstream remote. 1. From a terminal, clone the repository: ```sh - $ git clone git@github.com:/pantheon.git + $ git clone git@github.com:/publishing-tutorial-sample-repo.git ``` -1. Set up `redhataccess/pantheon` as the upstream: +1. Set up `redhat-documentation/publishing-tutorial-sample-repo` as the upstream: ```sh - $ cd pantheon - $ git remote add upstream git@github.com:redhataccess/pantheon.git + $ cd publishing-tutorial-sample-repo + $ git remote add upstream git@github.com:redhat-documentation/publishing-tutorial-sample-repo.git ``` ### Creating a working branch -Whenever you work on a new issue, you must create a new working branch based on the latest version of the upstream master branch. +Pull requests should have a corresponing issue in the repo. Whenever you work on a new issue, you must create a new working branch based on the latest version of the upstream main branch. -1. Ensure you are on master +1. Ensure you are on main ```sh - $ git checkout master + $ git checkout main ``` 1. Ensure your fork is up to date ```sh - $ git pull upstream master + $ git pull upstream main ``` -1. Create a working branch based on the issue in JIRA. For example: - +1. Create a working branch based on the issue ID. For example for issue #2, you can use "2" or "02" for the branch name: ```sh - $ git checkout -b FCCEUD- + $ git checkout -b 02 ``` ### Creating a pull request and completing review @@ -90,11 +73,10 @@ When your work is ready to be reviewed and merged, create a pull request. ``` 1. From the repository page in GitHub, click **New pull request**. 1. Select your working branch from the compare list. -1. Add `WIP:` to the title of the pull request. This automatically converts the pull request to a draft pull request. +1. Add `WIP:` to the title of the pull request. This automatically converts the pull request to a draft pull request, preventing it from being merged. 1. Click **Create new pull request**. 1. Add the **awaiting tech review** label to the pull request. -1. In the pull request comment field, enter `@redhataccess/eud-tech-review Please review for technical completeness and accuracy`. - +1. In the pull request comment field, enter `@redhat-documentation/publishing-tutorial-team Please review for technical completeness and accuracy`. ### The review process @@ -106,15 +88,11 @@ After creating and labeling a pull request as outlined above, the developers rev When technical review is complete, writers click the **Reviewers** gear icon and select the name of a team member to request peer review. The peer writer reviews the pull request for clarity, consistency, and compliance with necessary standards. Writers receive a notification that comments have been added via email, and when all comments have been addressed, the reviewer clicks **Review changes > Approve** from the **Files changed** tab of the pull request to approve the changes and the pull request. -#### Code review - -For code pull requests, one or more developers review the pull request. A contributor submits a PR and uses Github's **Reviewers** gear icon to tag `@redhataccess/pantheon-developers`. A developer comments on the code, and discusses it with the submitter, before ultimately deciding to accept or reject the PR. - ### Merging a pull request When you have addressed all technical review and peer review comments, notify the developers to accept the pull request. 1. Remove `WIP` from the title of the pull request. -1. Click **Request Review** and enter `@redhataccess/pantheon-developers`. +1. Click **Request Review** and enter `@@redhat-documentation/publishing-tutorial-team`. The developers check that the **Tech review complete** label has been added to the pull request and peer pull request approval provided, then accept it. From 5e373bf8d632dba1a99edd7af7dcc85223aa9a6f Mon Sep 17 00:00:00 2001 From: sgoodman Date: Wed, 18 Aug 2021 17:43:17 +0300 Subject: [PATCH 3/3] contributing Peer review comments. --- README.md | 26 +++++++++----------------- 1 file changed, 9 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index cf36116..304d9d4 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ # Publishing tutorial sample repo -A sample repo to be used in conjunction with the tutorial "Getting started publishing with Pantheon 2" +A sample repository that you can use during the "Getting started publishing with Pantheon 2" tutorial. * [Contributing to this repository](#contributing-to-this-repository) @@ -7,13 +7,13 @@ A sample repo to be used in conjunction with the tutorial "Getting started publi ### Filing a bug -If you have any suggestions to improve or extend this repository, add a new issue in the repository. +If you have any suggestions to improve or extend this repository, open a [new issue](https://github.com/redhat-documentation/publishing-tutorial-sample-repo/issues) in the repository. ### Prerequisites -* You must have an account on GitHub. +* Have a GitHub account. [Signing up for a new GitHub account](https://help.github.com/en/github/getting-started-with-github/signing-up-for-a-new-github-account) -* You must have registered SSH keys in your GitHub account. +* Have your SSH key added to your GitHub account. [Adding a new SSH key to your GitHub account](https://help.github.com/en/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account) * You must be a member of the `pantheon-developers` or `pantheon-doc-authors` team in the `redhataccess` group in GitHub. * You must be logged in to your account on GitHub. @@ -62,7 +62,7 @@ Pull requests should have a corresponing issue in the repo. Whenever you work on $ git checkout -b 02 ``` -### Creating a pull request and completing review +### Creating a pull request and requesting a review When your work is ready to be reviewed and merged, create a pull request. @@ -73,26 +73,18 @@ When your work is ready to be reviewed and merged, create a pull request. ``` 1. From the repository page in GitHub, click **New pull request**. 1. Select your working branch from the compare list. -1. Add `WIP:` to the title of the pull request. This automatically converts the pull request to a draft pull request, preventing it from being merged. +1. Add the `WIP:` prefix to the title of the pull request. This automatically converts the pull request to a draft pull request, preventing it from being merged. 1. Click **Create new pull request**. 1. Add the **awaiting tech review** label to the pull request. 1. In the pull request comment field, enter `@redhat-documentation/publishing-tutorial-team Please review for technical completeness and accuracy`. ### The review process -Both the technical review and peer review processes take place in pull requests in GitHub. - -#### Documentation review -After creating and labeling a pull request as outlined above, the developers review the pull request and add comments regarding technical accuracy. Writers receive a notification that comments have been added via email, and when all comments have been addressed, the developers change the label from **awaiting tech review** to **tech review complete**. - -When technical review is complete, writers click the **Reviewers** gear icon and select the name of a team member to request peer review. The peer writer reviews the pull request for clarity, consistency, and compliance with necessary standards. -Writers receive a notification that comments have been added via email, and when all comments have been addressed, the reviewer clicks **Review changes > Approve** from the **Files changed** tab of the pull request to approve the changes and the pull request. +At least one person on the project team reviews the merge request and adds comments in GitHub. This review process will be open for one week from the day the merge request was submitted. If the merge request is still being actively discussed beyond the one week timeframe, then the merge request will stay open. Once the merge request discussion is resolved, the merge request will be NACK'd or ACK'd based on the comments given. If no comments are given after a week, then a project administrator will ACK the merge request. ### Merging a pull request -When you have addressed all technical review and peer review comments, notify the developers to accept the pull request. +After you have implemented all reviewer comments and received an ACK from an administrator, the pull request is ready to be merged. 1. Remove `WIP` from the title of the pull request. -1. Click **Request Review** and enter `@@redhat-documentation/publishing-tutorial-team`. - -The developers check that the **Tech review complete** label has been added to the pull request and peer pull request approval provided, then accept it. +1. Request that an Administrator merge the pull request.