From 620ba300ac5ed8cff65c840ee8106f4adbfadedf Mon Sep 17 00:00:00 2001 From: Jared Smith Date: Mar 02 2018 18:10:24 +0000 Subject: Merge branch 'master' of ssh://pagure.io/fedora-docs/documentation-guide --- diff --git a/_distro_map.yml b/_distro_map.yml index 62870ad..e55d33e 100644 --- a/_distro_map.yml +++ b/_distro_map.yml @@ -1,11 +1,11 @@ --- fedora: - name: Fedora Installation Guide + name: Fedora Documentation Guide author: Fedora Documentation Project site: main site_name: Home site_url: https://docs.fedoraproject.org/ branches: master: - name: Rawhide - dir: master + name: documentation-guide + dir: documentation-guide diff --git a/_topic_map.yml b/_topic_map.yml index e8c7d14..56501e0 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -25,12 +25,12 @@ Name: Fedora Documentation Guide Dir: en-US Topics: - Name: Contributing - File: contributing + File: index - Name: Pull Requests File: pr - Name: Publishing Translations File: publishing-translation - - Name: Orginization + - Name: Organization File: repo-org - Name: Tools File: tools diff --git a/en-US/contributing.adoc b/en-US/contributing.adoc deleted file mode 100644 index a680309..0000000 --- a/en-US/contributing.adoc +++ /dev/null @@ -1,35 +0,0 @@ -= Contribute to Fedora Documentation - -== 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 - - -[[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]. - -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 -* System Administrator's Guide - https://pagure.io/fedora-docs/system-administrators-guide - -This document is stored in https://pagure.io/fedora-docs/documentation-guide diff --git a/en-US/index.adoc b/en-US/index.adoc new file mode 100644 index 0000000..234be01 --- /dev/null +++ b/en-US/index.adoc @@ -0,0 +1,31 @@ += Contribute to Fedora documentation + +== 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. + +* 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 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: + +* 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. 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]. diff --git a/index-main.html b/index-main.html index f8801fc..e3ae701 100644 --- a/index-main.html +++ b/index-main.html @@ -29,17 +29,14 @@
-

Fedora Documentation Site

+

Fedora Documentation Guide Site

Test Build.

-
Fedora Documentation
+
Fedora Documentation Guide
- -  Fedora 26 Documentation - - -  Rawhide Documentation + +  Current Documentation