| |
@@ -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].
|
| |