Hi docs team,
In response to a few conversations I've had with folks, I put together a basic guide to git for docs writers:
https://fedoraproject.org/wiki/User:Bcotton/git-for-docs-writers
I appreciate your feedback, bearing in mind that I intentionally wrote this to be a single way of doing things to focus on getting the job done instead of teaching the reader all of the different ways to do a task.
If it's useful, I'm happy to asciidoc it and put it somewhere (I'm just not sure where).
Thanks, BC
Hey Ben,
On 12/16/19 4:04 PM, Ben Cotton wrote:
Hi docs team,
In response to a few conversations I've had with folks, I put together a basic guide to git for docs writers:
https://fedoraproject.org/wiki/User:Bcotton/git-for-docs-writers
This is useful. An opinionated way of doing things helps. It would be awesome to integrate this into the Fedora Docs contributor guidelines.
I appreciate your feedback, bearing in mind that I intentionally wrote this to be a single way of doing things to focus on getting the job done instead of teaching the reader all of the different ways to do a task.
To make this more effective and improve its reach, consider assuming the reader uses any of a range of operating systems. It might help to offer pointers for macOS, Windows, maybe DEB/APT users.
I am thinking of my experience in Fedora's Telegram, Reddit, and Discord, where community members were frequently interested in improving or enhancing docs when gently prompted. Often times, people may use Fedora in a project-specific or at their work, but their private, personal machine (where they contribute from) is not Fedora.
If it's useful, I'm happy to asciidoc it and put it somewhere (I'm just not sure where).
I think the most-visible place for people wanting to contribute to Fedora Docs is here:
https://docs.fedoraproject.org/en-US/fedora-docs/contributing/
So maybe this is a good place to start?
https://pagure.io/fedora-docs/documentation-contributors-guide/blob/master/f...
On Mon, Dec 16, 2019 at 5:08 PM Justin W. Flory jflory7@gmail.com wrote:
To make this more effective and improve its reach, consider assuming the reader uses any of a range of operating systems. It might help to offer pointers for macOS, Windows, maybe DEB/APT users.
I added a "hey, this basically works on any OS" note with a link to the Git docs for info on installing on other OSes. I'm hesitant to add any more than that because it gets away from the "here's a no-options" approach and apart from the package install pre-reqs, everything else should work.
I think the most-visible place for people wanting to contribute to Fedora Docs is here:
https://docs.fedoraproject.org/en-US/fedora-docs/contributing/So maybe this is a good place to start?
https://pagure.io/fedora-docs/documentation-contributors-guide/blob/master/f...
Makes sense to me. I wonder if it should be slightly broadened to apply to other non-code git repos, but it may make sense to leave it as-is, put it there, and point other folks to it when needed.
If nobody else raises strong objections, I'll submit a PR later this week to add it.
On 12/16/19 5:18 PM, Ben Cotton wrote:
On Mon, Dec 16, 2019 at 5:08 PM Justin W. Flory jflory7@gmail.com wrote:
To make this more effective and improve its reach, consider assuming the reader uses any of a range of operating systems. It might help to offer pointers for macOS, Windows, maybe DEB/APT users.
I added a "hey, this basically works on any OS" note with a link to the Git docs for info on installing on other OSes. I'm hesitant to add any more than that because it gets away from the "here's a no-options" approach and apart from the package install pre-reqs, everything else should work.
I was thinking of Podman at first, but Podman wasn't covered in the doc. If you linked out to platform-specific docs for each of the pre-reqs, I think that is sufficient to enable readers to help themselves.
On Mon, Dec 16, 2019 at 10:05 PM Ben Cotton bcotton@redhat.com wrote:
Hi docs team,
In response to a few conversations I've had with folks, I put together a basic guide to git for docs writers:
Thank you for putting this together. It has been needed!
https://fedoraproject.org/wiki/User:Bcotton/git-for-docs-writers
I appreciate your feedback, bearing in mind that I intentionally wrote this to be a single way of doing things to focus on getting the job done instead of teaching the reader all of the different ways to do a task.
I have an alternative approach that I like that I feel like makes it easier to keep the fork in sync. This feels like a huge point of friction for new users and this is hte only reason I am proposing it.
1. Go to Pagure to the docs repo and get the clone URL (this may be an https url and that is OK) 2. On your system clone this url: `git clone <docs repo clone url> -o upstream` This will create the repo as a remote called upstream. This is mostly a detail and can be glossed over 3. Fork the repo in the Pagure UI 4. Copy your fork clone url (git@...) 5. `cd <repo directory> 6. `git remote add origin <fork clone url>`
At this point the master branch is linked to "upstream" and the fork is origin. What this means is that, following hte rest of the directions, keeping the repo in sync is as simple as `git checkout master; git pull`
regards,
bex
If it's useful, I'm happy to asciidoc it and put it somewhere (I'm just not sure where).
Thanks, BC
-- Ben Cotton He / Him / His Fedora Program Manager Red Hat TZ=America/Indiana/Indianapolis _______________________________________________ docs mailing list -- docs@lists.fedoraproject.org To unsubscribe send an email to docs-leave@lists.fedoraproject.org Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org
On 12/18/19 6:54 AM, Brian (bex) Exelbierd wrote:
I have an alternative approach that I like that I feel like makes it easier to keep the fork in sync. This feels like a huge point of friction for new users and this is hte only reason I am proposing it.
- Go to Pagure to the docs repo and get the clone URL (this may be an
https url and that is OK) 2. On your system clone this url: `git clone <docs repo clone url> -o upstream` This will create the repo as a remote called upstream. This is mostly a detail and can be glossed over 3. Fork the repo in the Pagure UI 4. Copy your fork clone url (git@...) 5. `cd <repo directory> 6. `git remote add origin <fork clone url>`
At this point the master branch is linked to "upstream" and the fork is origin. What this means is that, following hte rest of the directions, keeping the repo in sync is as simple as `git checkout master; git pull`
+1 to this tip! That's a clever trick to get master linked to a different remote from other branches. It also makes feature branching easier to understand when things are set up this way.
Today I learned :)
First I would like to offer a huge thank you to Ben for making this tutorial. I really appreciate his efforts, because I am one of the members of his target audience. I'm continuing to try, but git is not clicking for me as well as I had hoped. Here are some thoughts and questions that I had as I review Ben's work this morning when I attempted to do some editing of the doc files. 1. I like Ben's approach of presenting just one workflow to get new people like me up and running. I imagine as I learn more or use different tools, I might find different ways of working, but having one template of steps that always works that I can come back to after not touching the docs for a week or two would be nice. 2. I also appreciate that Ben focused the docs on Fedora as the environment. For a complete new person like myself, I'm looking to give back to Fedora as a thanks for what Fedora has enabled me to do with my computer, so I would like to test the documentation on Fedora and edit the documentation on Fedora. I also understand that there are other users that might be doing work for Fedora on other systems. Personally, I'm using Fedora 100% of the time at home, but I'm using Win10 and Ubuntu Mate at work. I think Ben is right though that for this "Quick Start Guide" for new users and contributors to Fedora it might be best to focus the docs just on Fedora. 3. https://fedoraproject.org/wiki/User:Bcotton/git-for-docs-writers#Before_ever... - Would it be a good idea to add in this section the following additional command?
git push origin master - The reason I ask is because I knew that my Pagure fork was out of sync because I couldn't see in the webview of my Pagure fork an update that I knew had been accepted by the Docs team. After running this additional command, I could see the changes in my Pagure fork webview. This way when I go to my Pagure fork webview I should see the exact same thing as what is appearing on the Fedora Master Pagure webview. I appreciated this confirmation that I had everything in sync. 4. The following question came up when I started making edits that I didn't have the time to finish today.- I understand that ++git checkout -b branch_name++ puts me into my working branch that I have created.- However if I need to close my text editor and come back to my edits later, how do I know if I'm still making those edits in my "work in progress" branch instead of my forked "master" branch?- Do I fire up a terminal and just run ++git checkout -b branch_name++ again?- Or is there a "status" type command that I would run from the terminal to know what branch I'm making my edits in? Thanks again for providing this resource for a new contributor like me. I really admire the more talented and knowledgeable community members on the docs team who have helped me so far. I have gotten some great help in the fedora-docs IRC besides this mailing list. Thank you!
---------------------------- | Steve | | mowestusa@yahoo.com | ----------------------------
On Wednesday, December 18, 2019, 7:11:14 AM EST, Justin W. Flory jflory7@gmail.com wrote:
On 12/18/19 6:54 AM, Brian (bex) Exelbierd wrote:
I have an alternative approach that I like that I feel like makes it easier to keep the fork in sync. This feels like a huge point of friction for new users and this is hte only reason I am proposing it.
- Go to Pagure to the docs repo and get the clone URL (this may be an
https url and that is OK) 2. On your system clone this url: `git clone <docs repo clone url> -o upstream` This will create the repo as a remote called upstream. This is mostly a detail and can be glossed over 3. Fork the repo in the Pagure UI 4. Copy your fork clone url (git@...) 5. `cd <repo directory> 6. `git remote add origin <fork clone url>`
At this point the master branch is linked to "upstream" and the fork is origin. What this means is that, following hte rest of the directions, keeping the repo in sync is as simple as `git checkout master; git pull`
+1 to this tip! That's a clever trick to get master linked to a different remote from other branches. It also makes feature branching easier to understand when things are set up this way.
Today I learned :)
On Wed, Dec 18, 2019 at 6:56 AM Brian (bex) Exelbierd bexelbie@redhat.com wrote:
I have an alternative approach that I like that I feel like makes it easier to keep the fork in sync. This feels like a huge point of friction for new users and this is hte only reason I am proposing it.
I think I captured this in the latest version, can you please take a look and make sure I'm not misrepresenting it? https://fedoraproject.org/wiki/User:Bcotton/git-for-docs-writers
On Mon, Dec 23, 2019 at 12:10 PM mowestusa mowestusa@yahoo.com wrote:
- Would it be a good idea to add in this section the following additional command?
git push origin master
Good point! I don't use the web interface much, so I didn't think of that. I added it to my draft.
- The following question came up when I started making edits that I didn't have the time to finish today.
- I understand that ++git checkout -b branch_name++ puts me into my working branch that I have created.
- However if I need to close my text editor and come back to my edits later, how do I know if I'm still making those edits in my "work in progress" branch instead of my forked "master" branch?
- Do I fire up a terminal and just run ++git checkout -b branch_name++ again?
- Or is there a "status" type command that I would run from the terminal to know what branch I'm making my edits in?
`git branch` will tell you the current branch, along with the other branches it knows about. Your current branch starts with *. I added a tip to the "Making a contribution" section: https://fedoraproject.org/wiki/User:Bcotton/git-for-docs-writers#Making_a_co...
Thanks again Ben, for addressing my little niggles. I have reviewed your additions, and I feel it is a wonderful resource that I can use often until git just rolls off of the finger tips.
---------------------------- | Steve | | mowestusa@yahoo.com | ----------------------------
On Thursday, January 2, 2020, 4:44:14 PM EST, Ben Cotton bcotton@redhat.com wrote:
On Wed, Dec 18, 2019 at 6:56 AM Brian (bex) Exelbierd bexelbie@redhat.com wrote:
I have an alternative approach that I like that I feel like makes it easier to keep the fork in sync. This feels like a huge point of friction for new users and this is hte only reason I am proposing it.
I think I captured this in the latest version, can you please take a look and make sure I'm not misrepresenting it? https://fedoraproject.org/wiki/User:Bcotton/git-for-docs-writers
On Mon, Dec 23, 2019 at 12:10 PM mowestusa mowestusa@yahoo.com wrote:
- Would it be a good idea to add in this section the following additional command?
git push origin master
Good point! I don't use the web interface much, so I didn't think of that. I added it to my draft.
- The following question came up when I started making edits that I didn't have the time to finish today.
- I understand that ++git checkout -b branch_name++ puts me into my working branch that I have created.
- However if I need to close my text editor and come back to my edits later, how do I know if I'm still making those edits in my "work in progress" branch instead of my forked "master" branch?
- Do I fire up a terminal and just run ++git checkout -b branch_name++ again?
- Or is there a "status" type command that I would run from the terminal to know what branch I'm making my edits in?
`git branch` will tell you the current branch, along with the other branches it knows about. Your current branch starts with *. I added a tip to the "Making a contribution" section: https://fedoraproject.org/wiki/User:Bcotton/git-for-docs-writers#Making_a_co...
On Thu, Jan 2, 2020 at 10:44 PM Ben Cotton bcotton@redhat.com wrote:
On Wed, Dec 18, 2019 at 6:56 AM Brian (bex) Exelbierd bexelbie@redhat.com wrote:
I have an alternative approach that I like that I feel like makes it
easier to keep the fork in sync. This feels like a huge point of friction for new users and this is hte only reason I am proposing it.
I think I captured this in the latest version, can you please take a look and make sure I'm not misrepresenting it? https://fedoraproject.org/wiki/User:Bcotton/git-for-docs-writers
I suggest the following changes:
1. Delete the first section under "🔗 Before your first edit" and fold it into the detail that follows.
This requires the fork to be created as part of hte major step 2 below that heading. I would rewrite "Go to your forked Pagure repo" as "Create your fork repo" and make step 1 of it to hit hte fork button in the web interface.
This change should allow for to be created in a smooth single flow with no back/forths in the web interface.
regards,
bex
On Mon, Dec 23, 2019 at 12:10 PM mowestusa mowestusa@yahoo.com wrote:
https://fedoraproject.org/wiki/User:Bcotton/git-for-docs-writers#Before_ever...
- Would it be a good idea to add in this section the following
additional command?
git push origin master
Good point! I don't use the web interface much, so I didn't think of that. I added it to my draft.
- The following question came up when I started making edits that I
didn't have the time to finish today.
- I understand that ++git checkout -b branch_name++ puts me into my
working branch that I have created.
- However if I need to close my text editor and come back to my edits
later, how do I know if I'm still making those edits in my "work in progress" branch instead of my forked "master" branch?
- Do I fire up a terminal and just run ++git checkout -b branch_name++
again?
- Or is there a "status" type command that I would run from the terminal
to know what branch I'm making my edits in?
`git branch` will tell you the current branch, along with the other branches it knows about. Your current branch starts with *. I added a tip to the "Making a contribution" section:
https://fedoraproject.org/wiki/User:Bcotton/git-for-docs-writers#Making_a_co...
-- Ben Cotton He / Him / His Fedora Program Manager Red Hat TZ=America/Indiana/Indianapolis _______________________________________________ docs mailing list -- docs@lists.fedoraproject.org To unsubscribe send an email to docs-leave@lists.fedoraproject.org Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org
On Mon, Jan 6, 2020 at 4:27 AM Brian (bex) Exelbierd bexelbie@redhat.com wrote:
I suggest the following changes:
Done!
PR submitted: https://pagure.io/fedora-docs/documentation-contributors-guide/pull-request/...
Thanks everyone for your feedback!
-
Ben Cotton -
Brian (bex) Exelbierd -
Justin W. Flory -
mowestusa