Q and A
<Emad78> How do I know what "branch" to use when editing a doc. Will someone tell me exactly which one to use. <Emad78> Also I can just follow the git wiki commands to do that stuff?
<quaid> here's the basic idea: <quaid> * If the bug is filed against a specific version of a document that ties to a specific version of software, so the bug is only applicable to that version of the document, then we want to fix the bug in the branch associated with that version. <quaid> typically that branc is "F-12" or some such. <quaid> * However, in docs it's common that the bug needs fixing in all versions, so that might mean fixing it in HEAD and then committing the same change in the other branches <quaid> also, we don't support (fix) docs that are tied to a release of Fedora that is no longer supported. <quaid> the git guide on the wiki has most of the commands you need, I think.
<Emad78> Ok, so when I made all those edits on the UG, I made a bunch of changes in 4 files. Is it good to do so many changes and do one commit for all of them? <quaid> it depends :) <quaid> are they all a fix for one bug report? <quaid> if so, one commit is fine <quaid> one per bug report is a good measure <quaid> another example of where to split: <quaid> if you make big structure changes, do those first and commit, then do content changes (clean-up, typos, etc.) as a second commit <quaid> it makes it easier for others to review the work and see the impact. <quaid> one nice thing about git, if you haven't discovered it, is that committing is easy since it's a local event; I find myself committing more often for more granular reasons because it's "cheap" and can be done offline.
- quaid was a CVS and SVN user for many years and dreaded each commit.
<Emad78> Ok, So the proper etiquette is to ask the Doc owner before doing a bug fix then right. Cause there might be a couple fixes I can do to keep on learning> <quaid> it depends :) <quaid> you can put a note in the bug report that you'd like to fix it, or go ahead and show the fix. <quaid> if you've been given commit rights to the doc repository by the doc owner <quaid> you have already been given what you need to make your own decision - if you think you have it (or even may have it), do the fix and commit it. <quaid> you can note in the bug report that you made a commit (link) and think it fixes the bug., if so, please close. <quaid> of course, if you keep doing that, you'll end up with bugs assigned to you :) <quaid> remember -- source control management means never having to say you are sorry <quaid> if your fix doesn't work, it can be backed out, or more likely, just tweaked in the next commit.
<Emad78> I'm usually full of them, so I never know when they pop up. teachingopensource.org <quaid> Emad78: one nice thing about IRC is the asynchronous nature of it <quaid> I leave my client running all the time in a way I can detach from, so if you ask questions or comment <quaid> I see it later and reply <Emad78> Yes this is way easier than emailing a ton to you. <quaid> we have discussions that span timezones and never even be together in the channel at the same time <quaid> right, but it misses some of the value of mailing lists -- it's a balance <Emad78> I hear ya. <quaid> for example, in the mailing list many more get to read the above advice; but it can be inconvenient for every little thing <quaid> anyway, don't be afraid to leave questions in the channel and see who answers :) <quaid> because we are "just like" coding projects, even non-docs team participants might know the right answer, etc. <Emad78> Yeah, and I figured these were pretty easy to answer. And since I was on here I thought I would see if anyone was around.
<quaid> since the textbook I'm working on includes this sort of material, I'll likely reference it to the list later, see if it's useful to newer contributors, etc. <Emad78> Yeah that's true. Maybe if I gather a bunch of new contributor questions I can email the list. You think we could do a new contributor FAQ type thing??
<laubersm> Emad78, you can just start creating one in the wiki ;) <laubersm> Thanks quaid for answering... I'm not really here yet... been busier than I thought for the day <laubersm> and I have a few more things to do before dark. Then one other chapter to review before I can dig into the UG stuff. <laubersm> My *plan* (that is failing miserably so far) was to see what had to be done so I could get a task list going somewhere (trac or wiki depending on what I find) <Emad78> laubersm: I would need some direction in starting something like that on the wiki. <laubersm> Emad78, is doing a great job killin goff the bugs! <laubersm> Emad78, can do - just not for at least another couple of hours. <laubersm> others might be able to help sooner (hint hint quaid) <Emad78> laubersm: Oh no it doesn't have to be right now. But SOON would be good. <laubersm> Emad78, keep making notes. we will eventually get to them.
- laubersm is off to finish other stuff now...
<quaid> Emad78: there's a cultural thing in FLOSS about "annoying newbies", both from the perspective of the experienced contributor and the person who may feel like an annoying newbie! <quaid> https://www.theopensourceway.org/wiki/Stuff_everyone_knows_and_forgets_anyway#Turn_annoying_newbies_in_to_instant_contributors_with_the_power_of_To_Document <quaid> that's what laubersm just did to you :) <quaid> which I was also considering, so I'm happy to help get that flow <quaid> for super-easy you might want to make a page in your personal "sandbox" on the wiki, that is, the pages under your user name: <quaid> User:Emad78/New_Docs_contributor_FAQ_dump <quaid> then copy and paste our discussion from above in to there as a quick grab and reminder :) <quaid> you can actually construct the whole thing there, then 'move' it later to Docs new contributor FAQ <Emad78> Well ok then, on to being a "contributor" then. Thanks laubersm ;) <Emad78> quaid: This (theopensourceway.org) is a good read.
> You emailed before I could get the chance to email you. Quick again. I > was going to ask you about the EDITOR and VISUAL. And I remember what > you said about putting it into bash.rc. And I will just put them in > there since I'm the only user. But do I need to put anything in there to > allow them to do their job. I don't really know the lingo but, like a > header or title. Something like that, to allow them to work. Or just put > them in straight away? I'll do that then we can figure it out if it > doesn't work.
If you are going to do it system-wide, it is probably better to put it in /etc/profile.d. This has a file per "thing" you want to do. I have an "editor.sh" that sets this up. It has the lines I said, except emacs of course, instead of gedit, and it begins with a ~!/bin/sh. Not so sure it is really necessary, but I also gave it chmod +x. During logon not all scripts seem to need execute, but I do it by habit. So my entire /etc/profile.d/editor.sh is:
EDITOR=emacs VISUAL=emacs export EDITOR VISUAL
Anything ending with .sh in profile.d gets executed if bash is your default shell, everything ending in .csh gets executed if your shell is csh.
> I had alot of fun working with you guys yesterday. I didn't know what it > would be like but it was fun. The time flew by that's for sure. It was > great. I had a good time.
I'm glad you enjoyed it, it is a lot of fun, even more as you get to know the folks.
> So now. How does the pecking order work. Like I just jumped in and did > that one bug for the user-guide. Now I applied to be on the group and > got approved. So does that mean I can just jump in and do any bug I feel > comfortable with doing? Do I need to ask permission from the owner? How > does all that work out?
Of course, it is good form to talk to the owner, but the rule in Fedora is kind of "don't ask, always tell!". The philosophy is as little governance as possible. Max Spevack did an excellent talk, I'll see if I can't find the link. We try to be ruthelessly open. Whenever possible all decisions are made on the mailing list, although a lot of on the fly things happen on IRC. IRC is kind of open, but people who don't happen to be there don't see it. We try to document anything significant on the wiki.
Sparks is the Docs Project Leader, he has been under the weather lately so he wasn't around much over the weekend. Sparks works as a contractor for the military in Virginia. I think he is kind of a young guy, maybe 30-ish. (I'm an old guy in case you didn't realize!). The Wikiczar is ianweller, he is the expert on all things wiki, and is in the process of looking for a college, so we have all ends of the spectrum.
stickster is the Fedora Project Leader, he may be the only person paid to do this Fedora stuff full-time, but there are LOTS of paid Red Hat folks working on Fedora. Stickster is the guy the magazines interview about Fedora. quaid is Red Hat's "Community Architect". I think quaid and stickster started the Docs Project, but for a while stickster was pretty much a one-man show, so he really knows the space. He has been less involved since I've taken over release notes and spevack stepped down as Fedora Project Leader. Spevack is now heading the Ambassadors. Probably the only part of Fedora that actually has a budget!
> What do I do if I'm just reading a random document, like say the livecd > document. And I come across some errors in grammar or what not. Do I > fill out a bug and can just jump right in fix it. And then close the > bug?
That would work. If there is an owner, nice to tell him. The owners are listed on the meeting page for most of the docs.
> Sorry for all the questions. If there is a doc to read on all that I can > do that. But I was just wondering how the whole system worked and I > didn't want to step on toes, you know? > I mean I wouldn't do anything without asking first anyway but just > curious.
You know, if you really screw things up badly, with git it isn't a big deal do undo stuff. After translations start in earnest it can get to be messy, but you can always go back. One of the nice things about git.
OK, on your other email, most of the really important stuff is in ~/.ssh, so if you back up ALL your user files, you should be good.