3:04 p.m.
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
--
Ben Cotton
He / Him / His
Fedora Program Manager
Red Hat
TZ=America/Indiana/Indianapolis
4:06 p.m.
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/maste...
--
Cheers,
Justin W. Flory
justinwflory.com
TZ=America/New_York
Pronouns: he/him/his
4:18 p.m.
On Mon, Dec 16, 2019 at 5:08 PM Justin W. Flory <jflory7(a)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/maste...
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.
--
Ben Cotton
He / Him / His
Fedora Program Manager
Red Hat
TZ=America/Indiana/Indianapolis
8:27 p.m.
On 12/16/19 5:18 PM, Ben Cotton wrote:
On Mon, Dec 16, 2019 at 5:08 PM Justin W. Flory
<jflory7(a)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.
--
Cheers,
Justin W. Flory
justinwflory.com
TZ=America/New_York
Pronouns: he/him/his
5:54 a.m.
On Mon, Dec 16, 2019 at 10:05 PM Ben Cotton <bcotton(a)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(a)lists.fedoraproject.org
To unsubscribe send an email to docs-leave(a)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
--
Brian "bex" Exelbierd (he/him/his)
RHEL Product Management & Community Architect
@bexelbie | http://www.winglemeyer.org
bexelbie(a)redhat.com
6:10 a.m.
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.
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`
+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 :)
--
Cheers,
Justin W. Flory
justinwflory.com
TZ=America/New_York
Pronouns: he/him/his
11:08 a.m.
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_e...
- 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(a)yahoo.com |
----------------------------
On Wednesday, December 18, 2019, 7:11:14 AM EST, Justin W. Flory
<jflory7(a)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.
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`
+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 :)
--
Cheers,
Justin W. Flory
justinwflory.com
TZ=America/New_York
Pronouns: he/him/his
_______________________________________________
docs mailing list -- docs(a)lists.fedoraproject.org
To unsubscribe send an email to docs-leave(a)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
3:43 p.m.
On Wed, Dec 18, 2019 at 6:56 AM Brian (bex) Exelbierd
<bexelbie(a)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(a)yahoo.com> wrote:
3.
https://fedoraproject.org/wiki/User:Bcotton/git-for-docs-writers#Before_e...
- 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.
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?
`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...
--
Ben Cotton
He / Him / His
Fedora Program Manager
Red Hat
TZ=America/Indiana/Indianapolis
8:54 p.m.
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(a)yahoo.com |
----------------------------
On Thursday, January 2, 2020, 4:44:14 PM EST, Ben Cotton <bcotton(a)redhat.com>
wrote:
On Wed, Dec 18, 2019 at 6:56 AM Brian (bex) Exelbierd
<bexelbie(a)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(a)yahoo.com> wrote:
3.
https://fedoraproject.org/wiki/User:Bcotton/git-for-docs-writers#Before_e...
- 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.
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?
`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...
--
Ben Cotton
He / Him / His
Fedora Program Manager
Red Hat
TZ=America/Indiana/Indianapolis
_______________________________________________
docs mailing list -- docs(a)lists.fedoraproject.org
To unsubscribe send an email to docs-leave(a)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
3:26 a.m.
On Thu, Jan 2, 2020 at 10:44 PM Ben Cotton <bcotton(a)redhat.com> wrote:
On Wed, Dec 18, 2019 at 6:56 AM Brian (bex) Exelbierd
<bexelbie(a)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(a)yahoo.com> wrote:
>
> 3.
https://fedoraproject.org/wiki/User:Bcotton/git-for-docs-writers#Before_e...
> - 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.
> 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?
>
`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...
--
Ben Cotton
He / Him / His
Fedora Program Manager
Red Hat
TZ=America/Indiana/Indianapolis
_______________________________________________
docs mailing list -- docs(a)lists.fedoraproject.org
To unsubscribe send an email to docs-leave(a)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
--
Brian "bex" Exelbierd (he/him/his)
RHEL Product Management & Community Architect
@bexelbie | http://www.winglemeyer.org
bexelbie(a)redhat.com
9:39 a.m.
PR submitted:
https://pagure.io/fedora-docs/documentation-contributors-guide/pull-reque...
Thanks everyone for your feedback!
--
Ben Cotton
He / Him / His
Fedora Program Manager
Red Hat
TZ=America/Indiana/Indianapolis
1563
days inactive
1599
days old
11 comments
4 participants
participants (4)
-
Ben Cotton -
Brian (bex) Exelbierd -
Justin W. Flory -
mowestusa