From 30a587387d0f639c7b66d98e76232c33bc17fc09 Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Aug 15 2020 16:51:09 +0000 Subject: [PATCH 1/4] Docs/Contributing: Cover online editing - Prerequisites: Only FAS account is mandatory for online edits - Contributing: Split into sections: online, offline, and pr-management - Add Git tips box to online section --- diff --git a/modules/contributing/pages/contributing-to-existing-docs.adoc b/modules/contributing/pages/contributing-to-existing-docs.adoc index cf2063e..ddf9e29 100644 --- a/modules/contributing/pages/contributing-to-existing-docs.adoc +++ b/modules/contributing/pages/contributing-to-existing-docs.adoc @@ -2,20 +2,49 @@ This section describes how to contribute to existing documentation - that is, documentation that already has been published on the website. Before you start following this procedure, make sure that you fulfill all the requirements listed in xref:prerequisites.adoc[Prerequisites]. -. Find out which repository contains the sources which you want to edit. Generally, repository names correspond with the displayed names for each book. The list of repositories for Fedora Docs is at link:++https://pagure.io/fedora-docs/docs-fp-o++[]. -+ -[NOTE] +Each Fedora Docs page includes an "Edit this Page" link at the top. For simple updates, changes can be submitted directly from the Pagure web interface. For larger or more complex edits, you should prepare and test your changes offline before submitting. + +== Editing online in Pagure + +. Click the "Edit this Page" link to load the documentation source. You will be taken to the appropriate content repository in Pagure. + +. Above the source listing on the right side, click "Fork and Edit". (If you have already forked the repository, this button will be labeled "Edit in your fork" and you can skip to the next step.) + +.. If you are not already logged in to Pagure, you will be asked for your credentials. + +.. Wait for the operation to finish. You may need to refresh the page as it does not always update automatically when the process is done. + +. Once the file is loaded in your fork, make any changes necessary to the content, commit them to your fork, and prepare a pull request (PR). + +.. Each PR should be submitted from its own branch in your repository. Under the "Branch" heading of the commit interface, select "New branch" and give the branch a short, unique name. + +.. Fill out the commit message form. + +.. Click "Commit changes" to create the branch and save these changes to your fork. + +. Once the commit is saved, the page will refresh to a list of Commits for your fork. + +. To include additional, related changes, repeat this process and commit them to the same branch. + +. When you are ready, click "Create pull request" and fill out the PR form to submit your branch to the upstream repository. + +[TIP] +.Git commit tips ==== -We are planning to include an "edit this content" button on each page which will take you directly to the sources. However, this feature is not ready yet. +* When naming your branch, use only ASCII letters, digits, hyphens (`-`) and underscores (`_`). The name pass:q[_may_] contain, but not start or end with, single periods (`.`). Spaces, double periods (`..`), and most other punctuation are not permitted. +* The commit title is how your edit will be identified in the repository log for the page. It should be a brief summary of the changes made. The suggested title, "Update [filename]``pathname``", is sufficient for small edits. By [application]#Git# convention, the title should not end in a period. +* If you changes cannot be explained entirely by the title summary, use the "Commit Description" field to provide additional detail. But keep it short, and limited to only information that might be useful to a future editor reviewing the page's change history. You will have the opportunity to explain or discuss your changes when you submit your PR. ==== -. Once you have located the correct repository, make a fork if you do not have it forked already: +== Offline editing + +. Click the "Edit this Page" link to load the documentation source. You will be taken to the appropriate content repository in Pagure. Once you have located the correct repository, make a fork if you do not have it forked already: -.. Log in to Pagure using your FAS credentials. +.. In the top right corner, click Fork. -.. Open the original repository which contains the sources you want to edit. +.. If you are not already logged in to Pagure, you will be asked for your credentials. -.. In the top right corner, click Fork. Wait for the operation to finish. You may need to refresh the page as it does not always update automatically when the process is done. +.. Wait for the operation to finish. You may need to refresh the page as it does not always update automatically when the process is done. .. Clone your fork. @@ -27,13 +56,15 @@ We are planning to include an "edit this content" button on each page which will . Once you finish, commit your changes and push them to your fork. -. Use pagure to make a pull request from your fork to the main repository's master branch. +. Use Pagure to make a pull request from your fork to the main repository's master branch. + +== Managing your pull request + +Someone will see your pull request and either merge it, or provide feedback if there is something you should change. Work with the people commenting to make sure your contributions are up to standards. -. Someone will see your pull request and either merge it, or provide feedback if there is something you should change. Work with the people commenting to make sure your contributions are up to standards. -+ [NOTE] ==== If nobody reacts to your pull request in several days, try bringing it up on one of the link:++https://apps.fedoraproject.org/calendar/docs/++[weekly meetings], the IRC channel (`#fedora-docs` on FreeNode), or the link:++https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org/++[mailing list]. ==== -. Your changes will appear online sometime after the pull request is merged. The site is being updated daily. If your changes do not appear online within 60 hours of your PR being merged, ping `asamalik` (Adam Šamalík) on the IRC channel and ask him about it. +Your changes will appear online sometime after the pull request is merged. The site is being updated daily. If your changes do not appear online within 60 hours of your PR being merged, ping `asamalik` (Adam Šamalík) on the IRC channel and ask him about it. diff --git a/modules/contributing/pages/prerequisites.adoc b/modules/contributing/pages/prerequisites.adoc index 1c7fa96..c8f4ed0 100644 --- a/modules/contributing/pages/prerequisites.adoc +++ b/modules/contributing/pages/prerequisites.adoc @@ -1,11 +1,19 @@ = Prerequisites -Before you start contributing, you will need at least the following: +The only requirement for contributing documentation updates to Fedora Docs is: * A link:++https://admin.fedoraproject.org/accounts/++[*Fedora Account System*] (*FAS*) account. + +For larger updates or to contribute all-new documentation, you may also need: + * A plaintext editor such as [application]`vim`, [application]`emacs`, [application]`Atom`, etc., preferably with ASCIIDoc syntax highlighting. * [application]`git` and working knowledge of it. * [application]`Docker` for building and previewing your changes locally. * A working knowledge of the *ASCIIDoc* markup language. ++ +[NOTE] +==== +An *ASCIIDoc* markup guide specific to Fedora Docs is planned, but not yet ready. Until then, the link:++https://asciidoctor.org/docs/asciidoc-writers-guide/++[ASCIIDoc Writer's Guide] may be a helpful resource. +==== //See xref:markup.adoc[ASCIIDoc Markup]. From 844cd5b77b02e054e86cdf716335c1f4bf8a7d13 Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Aug 15 2020 16:51:09 +0000 Subject: [PATCH 2/4] Reformat sentence-per-line --- diff --git a/modules/contributing/pages/contributing-to-existing-docs.adoc b/modules/contributing/pages/contributing-to-existing-docs.adoc index ddf9e29..1c59eef 100644 --- a/modules/contributing/pages/contributing-to-existing-docs.adoc +++ b/modules/contributing/pages/contributing-to-existing-docs.adoc @@ -1,22 +1,29 @@ = Contributing to existing documentation -This section describes how to contribute to existing documentation - that is, documentation that already has been published on the website. Before you start following this procedure, make sure that you fulfill all the requirements listed in xref:prerequisites.adoc[Prerequisites]. +This section describes how to contribute to existing documentation - that is, documentation that already has been published on the website. +Before you start following this procedure, make sure that you fulfill all the requirements listed in xref:prerequisites.adoc[Prerequisites]. -Each Fedora Docs page includes an "Edit this Page" link at the top. For simple updates, changes can be submitted directly from the Pagure web interface. For larger or more complex edits, you should prepare and test your changes offline before submitting. +Each Fedora Docs page includes an "Edit this Page" link at the top. +For simple updates, changes can be submitted directly from the Pagure web interface. +For larger or more complex edits, you should prepare and test your changes offline before submitting. == Editing online in Pagure -. Click the "Edit this Page" link to load the documentation source. You will be taken to the appropriate content repository in Pagure. +. Click the "Edit this Page" link to load the documentation source. +You will be taken to the appropriate content repository in Pagure. -. Above the source listing on the right side, click "Fork and Edit". (If you have already forked the repository, this button will be labeled "Edit in your fork" and you can skip to the next step.) +. Above the source listing on the right side, click "Fork and Edit". +(If you have already forked the repository, this button will be labeled "Edit in your fork" and you can skip to the next step.) .. If you are not already logged in to Pagure, you will be asked for your credentials. -.. Wait for the operation to finish. You may need to refresh the page as it does not always update automatically when the process is done. +.. Wait for the operation to finish. +You may need to refresh the page as it does not always update automatically when the process is done. . Once the file is loaded in your fork, make any changes necessary to the content, commit them to your fork, and prepare a pull request (PR). -.. Each PR should be submitted from its own branch in your repository. Under the "Branch" heading of the commit interface, select "New branch" and give the branch a short, unique name. +.. Each PR should be submitted from its own branch in your repository. +Under the "Branch" heading of the commit interface, select "New branch" and give the branch a short, unique name. .. Fill out the commit message form. @@ -31,20 +38,32 @@ Each Fedora Docs page includes an "Edit this Page" link at the top. For simple u [TIP] .Git commit tips ==== -* When naming your branch, use only ASCII letters, digits, hyphens (`-`) and underscores (`_`). The name pass:q[_may_] contain, but not start or end with, single periods (`.`). Spaces, double periods (`..`), and most other punctuation are not permitted. -* The commit title is how your edit will be identified in the repository log for the page. It should be a brief summary of the changes made. The suggested title, "Update [filename]``pathname``", is sufficient for small edits. By [application]#Git# convention, the title should not end in a period. -* If you changes cannot be explained entirely by the title summary, use the "Commit Description" field to provide additional detail. But keep it short, and limited to only information that might be useful to a future editor reviewing the page's change history. You will have the opportunity to explain or discuss your changes when you submit your PR. +* When naming your branch, use only ASCII letters, digits, hyphens (`-`) and underscores (`_`). +The name pass:q[_may_] contain, but not start or end with, single periods (`.`). +Spaces, double periods (`..`), and most other punctuation are not permitted. + +* The commit title is how your edit will be identified in the repository log for the page. +It should be a brief summary of the changes made. +The suggested title, "Update [filename]``pathname``", is sufficient for small edits. +By [application]#Git# convention, the title should not end in a period. + +* If you changes cannot be explained entirely by the title summary, use the "Commit Description" field to provide additional detail. +But keep it short, and limited to only information that might be useful to a future editor reviewing the page's change history. +You will have the opportunity to explain or discuss your changes when you submit your PR. ==== == Offline editing -. Click the "Edit this Page" link to load the documentation source. You will be taken to the appropriate content repository in Pagure. Once you have located the correct repository, make a fork if you do not have it forked already: +. Click the "Edit this Page" link to load the documentation source. +You will be taken to the appropriate content repository in Pagure. +Once you have located the correct repository, make a fork if you do not have it forked already: .. In the top right corner, click Fork. .. If you are not already logged in to Pagure, you will be asked for your credentials. -.. Wait for the operation to finish. You may need to refresh the page as it does not always update automatically when the process is done. +.. Wait for the operation to finish. +You may need to refresh the page as it does not always update automatically when the process is done. .. Clone your fork. @@ -52,7 +71,8 @@ Each Fedora Docs page includes an "Edit this Page" link at the top. For simple u . If you added any new files, then ensure they are included in a reasonable spot in the repository's [filename]`nav.adoc` configuration file -. Build locally and make sure everything looks the way you expect. See xref:local-preview.adoc[Building a local preview] for instructions. +. Build locally and make sure everything looks the way you expect. +See xref:local-preview.adoc[Building a local preview] for instructions. . Once you finish, commit your changes and push them to your fork. @@ -60,11 +80,15 @@ Each Fedora Docs page includes an "Edit this Page" link at the top. For simple u == Managing your pull request -Someone will see your pull request and either merge it, or provide feedback if there is something you should change. Work with the people commenting to make sure your contributions are up to standards. +Someone will see your pull request and either merge it, or provide feedback if there is something you should change. +Work with the people commenting to make sure your contributions are up to standards. [NOTE] ==== If nobody reacts to your pull request in several days, try bringing it up on one of the link:++https://apps.fedoraproject.org/calendar/docs/++[weekly meetings], the IRC channel (`#fedora-docs` on FreeNode), or the link:++https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org/++[mailing list]. ==== -Your changes will appear online sometime after the pull request is merged. The site is being updated daily. If your changes do not appear online within 60 hours of your PR being merged, ping `asamalik` (Adam Šamalík) on the IRC channel and ask him about it. +Your changes will appear online sometime after the pull request is merged. +The site is being updated daily. +If your changes do not appear online within 60 hours of your PR being merged, ping `asamalik` (Adam Šamalík) on the IRC channel and ask him about it. + From f63ebcea4584734e7ecb893f5d0b752c9a2e2a18 Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Aug 15 2020 16:51:09 +0000 Subject: [PATCH 3/4] Rewrite git tips admonition --- diff --git a/modules/contributing/pages/contributing-to-existing-docs.adoc b/modules/contributing/pages/contributing-to-existing-docs.adoc index 1c59eef..2bfaed0 100644 --- a/modules/contributing/pages/contributing-to-existing-docs.adoc +++ b/modules/contributing/pages/contributing-to-existing-docs.adoc @@ -43,12 +43,10 @@ The name pass:q[_may_] contain, but not start or end with, single periods (`.`). Spaces, double periods (`..`), and most other punctuation are not permitted. * The commit title is how your edit will be identified in the repository log for the page. -It should be a brief summary of the changes made. The suggested title, "Update [filename]``pathname``", is sufficient for small edits. -By [application]#Git# convention, the title should not end in a period. +For some advice on writing good commit messages, see link:++https://commit.style[commit.style] by Tim Pope (author of [application]`vim`). -* If you changes cannot be explained entirely by the title summary, use the "Commit Description" field to provide additional detail. -But keep it short, and limited to only information that might be useful to a future editor reviewing the page's change history. +* Use the "Commit Description" field to provide additional detail if necessary, but keep it short. You will have the opportunity to explain or discuss your changes when you submit your PR. ==== From b5388b5694c3a03e6880c15087186522c92a01f8 Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Aug 15 2020 16:51:09 +0000 Subject: [PATCH 4/4] Format Prerequisites sentence-per-line --- diff --git a/modules/contributing/pages/prerequisites.adoc b/modules/contributing/pages/prerequisites.adoc index c8f4ed0..72f9800 100644 --- a/modules/contributing/pages/prerequisites.adoc +++ b/modules/contributing/pages/prerequisites.adoc @@ -13,7 +13,8 @@ For larger updates or to contribute all-new documentation, you may also need: + [NOTE] ==== -An *ASCIIDoc* markup guide specific to Fedora Docs is planned, but not yet ready. Until then, the link:++https://asciidoctor.org/docs/asciidoc-writers-guide/++[ASCIIDoc Writer's Guide] may be a helpful resource. +An *ASCIIDoc* markup guide specific to Fedora Docs is planned, but not yet ready. +Until then, the link:++https://asciidoctor.org/docs/asciidoc-writers-guide/++[ASCIIDoc Writer's Guide] may be a helpful resource. ==== //See xref:markup.adoc[ASCIIDoc Markup].