#3 Fix PR guidelines
Merged 6 years ago by rkratky. Opened 6 years ago by rkratky.
fedora-docs/ rkratky/documentation-guide misc-fixes  into  master

file modified
+18 -22
@@ -1,35 +1,31 @@ 

- = Contribute to Fedora Documentation

+ = Contribute to Fedora documentation

  

- == Different Ways to Contribute

+ == Different ways to contribute

  

- There are a few different ways you can contribute to Fedora

- documentation. While all of these are great ways to contribute, we've

- listed them in the order of maximum impact.

+ There are a few different ways you can contribute to Fedora documentation.

+ While all of these are great ways to contribute, we've listed them in the order of maximum impact.

  

- * If you would like to do the work yourself, or if it is a substantial

-    change, then you you should clone the repository, make your changes,

-    and submit a pull request (PR).  Each PR should have closely-related

-    changes.  In particular, it is a good idea to use separate PRs

-    for bugfix changes (for an old or current release) vs enhancement

-    changes (for an upcoming new release).  Further information about

-    link:pr.adoc[PRs is available] in this documentation set.

- * Create an issue in https://pagure.io/[pagure.io] in the appropriate

-    document's repository.  See xref:repository-list[Repository List]

-    below for more details.

- * Email the Fedora documentation team: docs@lists.fedoraproject.org

+ * To do the work yourself, or if it is a substantial change, you should clone the repository, make your changes, and submit a pull request (PR).

+ Each PR should have closely-related changes.

+ In particular, it is a good idea to use separate PRs for bug-fix changes (for an old or current release) vs enhancement changes (for an upcoming new release).

+ Further information about link:pr.html[PRs is available].

+ 

+ * Create an issue in https://pagure.io/[pagure.io] in the repository of the appropriate document.

+ See the link:#repository-list[Fedora Docs repository list] below for more details.

+ 

+ * Email the Fedora documentation team: docs@lists.fedoraproject.org.

  

  

  [[repository-list]]

- == Repository List

+ == Repository list

  

- Major documents and/or documentation sets are separated

- into separate repositories.  All repositories are stored in

- https://pagure.io/[pagure.io].

+ Major documents or documentation sets are separated into separate repositories.

+ All repositories are stored in https://pagure.io/[pagure.io].

  

  The major documents and documentations sets are:

  

- * Installation Guide - https://pagure.io/fedora-docs/install-guide

  * Release Notes - https://pagure.io/fedora-docs/release-notes

+ * Installation Guide - https://pagure.io/fedora-docs/install-guide

  * System Administrator's Guide - https://pagure.io/fedora-docs/system-administrators-guide

  

- This document is stored in https://pagure.io/fedora-docs/documentation-guide

+ This document is stored in https://pagure.io/fedora-docs/documentation-guide.

file modified
+49 -66
@@ -1,108 +1,91 @@ 

- = Pull Request Guidelines and Workflow

+ = Understanding pull-request workflow

+ 

+ Fedora documentation uses Git to store source files and facilitate collaboration. Using so-called pull requests is an established workflow for the Git version control system. This section provides basic guidelines for Git use and outlines a workflow to be followed when working with documentation repositories.

  

  == Guidelines

  

+ Learn about basic best practices to make collaboration streamlined.

+ 

  === Keep writing

  

- Provided a clear statement of the changes that are included in the

- PR. This will help the right people see your changes and will aid in

- getting them looked at faster.

+ Provide a clear statement of the changes that are included in the _pull request_ (PR).

+ This will help the right people see your changes and will aid in getting them reviewed faster.

  

  === Keep it small

  

- Giant dumps or edits make reviews a lengthy and time consuming

- process. For the sake of the review, and yourself keep PRs as small as

- you can while still making sense.

+ Giant dumps or edits make reviews a lengthy and time consuming process.

+ For the sake of the review and yourself, keep PRs as small as you can while still making sense.

  

- If you are providing a large number

- of edits to existing documents attempt to group them by section, or by

- the type of correction you are making. If you are adding new content

- keep limit each PR to a new page or section.

+ To provide a large number of edits to existing documents, group them by section, or by the type of correction you are making.

+ If you are adding new content keep limit each PR to a new page or section.

  

- However, each PR must be fully self-contained. The balance you want

- to strike is between readability and manageability of the PR and of

- ensuring that each PR, when committed, leaves the documentation logical

- and complete.

+ However, each PR must be fully self-contained.

+ The balance you want to strike is between readability and manageability of the PR and of ensuring that each PR, when committed, leaves the documentation logical and complete.

  

  === Keep it clean

  

- Histories are an extremely valuable part of using a version control

- system, but providing a history of your small changes may not be as

- useful. If you are the type of person who commits often locally, and

- tend to have lots of commits making up your PR look at using `git rebase`

- to combine commits into a smaller number of more verbose commits.

+ Histories are an extremely valuable part of using a version control system, but providing a history of your small changes may not be as useful.

+ If you are the type of person who commits often locally, and you tend to have lots of commits making up your PRs, look at using `git{nbsp}rebase` to combine commits into a smaller number of more verbose commits.

  

  === Keep paying attention

  

- As the PR submitter your job is not done once you start the process. Make

- sure to stay engaged and work with the people reviewing your changes.

+ As the PR submitter, your job is not done once you start the process.

+ Make sure to stay engaged and work with the people reviewing your changes.

  

  === Keep a good attitude 

  

- After putting a lot of work into something, it is natural to take reviews

- as a personal attack. Try and remember that this process is designed to

- help create the best possible end product for Fedora. It is important

- to keep that in mind and not to let it discourage you from continuing on.

+ After putting a lot of work into something, it is natural to take reviews as a personal attack.

+ Try and remember that this process is designed to help create the best possible end-product for Fedora.

+ It is important to keep that in mind and not to let it discourage you from continuing.

  

  == Workflow

  

- The sources for Fedora's documentation are stored in git repositories

- at https://pagure.io.  Contributions are accepted via `pull requests`,

- which merge changes from your copy of the repository into the original.

+ The sources for Fedora's documentation are stored in Git repositories at link:https://pagure.io[pagure.io].

+ Contributions are accepted via _pull requests_, which merge changes from your copy of the repository into the original.

  

- - Install the required link:tools.adoc[tools].

-   

- - Log into `pagure` and click the `Fork` button at the upper right hand

-   corner of a repository.  You now have a personal copy of the repo,

-   called a `fork`.

+ . Install the required link:tools.html[tools].

  

- - Clone your repository using the SSH URL.

+ . Log into Pagure and click the *Fork* button in the upper right-hand corner of a repository.

+ You now have a personal copy of the repo, called a _fork_.

  

+ . Clone your fork of the repository using the *SSH* URL.

+ +

  ....

- git clone ssh://git@pagure.io/forks/<fasi>/documentation-guide.git

- cd documentation-guide

+ $ git clone ssh://git@pagure.io/forks/<FAS_ID>/documentation-guide.git

+ $ cd documentation-guide

  ....

  

- - Create a branch to contain your work.  This makes it easier for others

-   to pull from your repo without disrupting their existing content.

-   You can name the branch anything, but something that correlates to

-   the work you'll be doing is best.

- 

+ . Create a branch to contain your work.

+ This makes it easier for others to pull from your repo without disrupting their existing content.

+ You can name the branch anything, but something that correlates to the work you'll be doing is best.

+ +

  ....

- git checkout -b pull_request_workflow

+ $ git checkout -b pull_request_workflow

  ....

  

- - Make your changes using the editor of your choice.  Add a commit for

-   each distinct change.

- 

+ . Make your changes using the editor of your choice.  Add a commit for each distinct change.

+ +

  ....

- git add en-US/pr.adoc

- git commit -m 'begin describing pull request workflow'

+ $ git add en-US/pr.adoc

+ $ git commit -m 'begin describing pull request workflow'

  ....

  

- - FIXME - how to build previews

- 

- - Push your changes to `pagure`.

+ . #FIXME# - how to build previews

  

+ . Push your changes to Pagure.

+ +

  ....

- git push origin

+ $ git push origin

  ....

  

- - FIXME - add how to keep your branch up to date with other changes

-   while working and how to do a final rebase to avoid merge conflicts

-   (by adding a `git remote`)

+ . #FIXME# - add how to keep your branch up to date with other changes while working and how to do a final rebase to avoid merge conflicts (by adding a `git remote`).

  

- - FIXME - add how to squash commits

+ . #FIXME# - add how to squash commits.

  

- - The new branch will now appear in your fork on pagure.  Once you have

-   pushed a cohesive set of changes, press the `New PR` button to start

-   a new pull request.  `pagure` will send your changes for review after

-   you fill out the form and press `Create`.

+ . The new branch will now appear in your fork on pagure.

+ Once you have pushed a cohesive set of changes, press the *New PR* button to start a new pull request.

+ Pagure will send your changes for review after you fill out the form and press *Create*.

  

- - Work with your reviewer to address any concerns.  Subsequent commits

-   pushed to this branch of your fork will be automatically included in

-   the pull request.

+ . Work with your reviewer to address any concerns. Subsequent commits pushed to this branch of your fork will be automatically included in the pull request.

  

- - Your changes get merged by the reviewer.  Congratulations!  Reward

-   yourself with a beer, you've earned it!  Soon you'll also earn a

-   https://badges.fedoraproject.org/[Fedora Badge]

+ . Your changes get merged by the reviewer. Congratulations! Reward yourself with your favorite treat, you've earned it! Soon you'll also earn a link:https://badges.fedoraproject.org/[Fedora Badge].

no initial comment

Pull-Request has been merged by rkratky

6 years ago

Greetings from docs-ci! The temporary URL for this PR is ready at: http://fedora-docs-documentation-guide-pr3-fedora-docs.apps.ci.centos.org

BuildID: 133

Metadata