From d61ff6106cf43a05b93ba1b26cfa766a628d2d1e Mon Sep 17 00:00:00 2001 From: Robert Krátký Date: Mar 02 2018 16:03:28 +0000 Subject: [PATCH 1/3] Fix: Contributing. --- diff --git a/en-US/index.adoc b/en-US/index.adoc index a680309..2184e21 100644 --- a/en-US/index.adoc +++ b/en-US/index.adoc @@ -2,34 +2,30 @@ == 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. - -* 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 +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. + +* 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 -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. From 96d578edba67fcbc3f309c7b709432c4bf0a5575 Mon Sep 17 00:00:00 2001 From: Robert Krátký Date: Mar 02 2018 17:30:07 +0000 Subject: [PATCH 2/3] More Contributing fixes. --- diff --git a/en-US/index.adoc b/en-US/index.adoc index 2184e21..234be01 100644 --- a/en-US/index.adoc +++ b/en-US/index.adoc @@ -1,6 +1,6 @@ -= 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. @@ -17,7 +17,7 @@ See the link:#repository-list[Fedora Docs repository list] below for more detail [[repository-list]] -== Repository List +== Repository list Major documents or documentation sets are separated into separate repositories. All repositories are stored in https://pagure.io/[pagure.io]. From d53531f4e516022a7ee00c44a3ca7c31c7ed73a7 Mon Sep 17 00:00:00 2001 From: Robert Krátký Date: Mar 02 2018 17:30:52 +0000 Subject: [PATCH 3/3] Fix PR guidelines. --- diff --git a/en-US/pr.adoc b/en-US/pr.adoc index cd17b0f..b6afde3 100644 --- a/en-US/pr.adoc +++ b/en-US/pr.adoc @@ -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//documentation-guide.git -cd documentation-guide +$ git clone ssh://git@pagure.io/forks//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].