| |
@@ -1,21 +1,67 @@
|
| |
= 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].
|
| |
|
| |
- . 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.
|
| |
+ The suggested title, "Update [filename]``pathname``", is sufficient for small edits.
|
| |
+ For some advice on writing good commit messages, see link:++https://commit.style[commit.style] by Tim Pope (author of [application]`vim`).
|
| |
+
|
| |
+ * 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.
|
| |
====
|
| |
|
| |
- . 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.
|
| |
|
| |
@@ -23,17 +69,24 @@
|
| |
|
| |
. 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.
|
| |
|
| |
- . 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.
|
| |
+
|
| |
ferdnyc
commented 4 years ago
The Contributing doc previously contained a NOTE admonition box about a 'planned' "Edit this Content" button. Since that button exists, I removed the admonition, and instead updated (rewrote, kind of) the page — and the Prerequisites, as a side-effect — to also cover online editing directly in Pagure.
<strike>I certainly don't expect such a large change will necessarily be adopted wholesale. So consider this PR as initiating discussion regarding the edit process and how it should be presented, more than a request to merge.</strike>
Given that said discussion has been had, and the commentary addressed, this now is a request to merge.
#TIL that strike tags do not work in Pagure comments.