From Fedora Project Wiki
Line 20: Line 20:
=== What is this "git" I keep hearing about? How does it pertain to the Docs Project? ===
=== What is this "git" I keep hearing about? How does it pertain to the Docs Project? ===


Git is a revision control system, and it's emphasis is on being fast. It is a working directory and full-fledged repository. It is used for keeping track of history and full revision tracking. To learn how to use git on the Docs Project see also [[Docs_Project_work_using_git]]. You can also read the Git Community Guide from the git project themselves here, http://book.git-scm.com
Git is a revision control system. It's emphasis is on being fast and efficient. It is a working directory and full-fledged repository. It is used for keeping track of history and full revision tracking. This is where all the documents are located in the repository for the Fedora Project. To learn how to use git on the Docs Project see also [[Docs_Project_work_using_git]]. You can also read the Git Community Guide from the git project themselves here, http://book.git-scm.com


=== What do I need to configure in git to work with documents? ===
=== What do I need to configure in git to work with documents? ===

Revision as of 02:27, 2 April 2010

DocsProject Header docTeam1.png
Note.png
This documented is maintained by Eli Madrinich. Feel free to edit the wiki or contact the maintainer for any kind of feedback.

This document is for anyone wanting to provide contributions to the Documentation Project. These are some of the most frequent questions asked by a new contributor. This document will not answer all of the questions you may have, but it will get you the basic ideas of what is needed to start helping out with the Docs Project.

Docs FAQ

What do I need to have installed to be able to work with the Documentation Project?

To get the applications you need to help out with the Docs Project you will need to install...........

Do I need to have any specific text editor to be able to edit documents?

No, you do not have to have a specific text editor. People use many different editors. Some of the most commonly used ones are

  • gedit
  • emacs
  • kate

What is this "git" I keep hearing about? How does it pertain to the Docs Project?

Git is a revision control system. It's emphasis is on being fast and efficient. It is a working directory and full-fledged repository. It is used for keeping track of history and full revision tracking. This is where all the documents are located in the repository for the Fedora Project. To learn how to use git on the Docs Project see also Docs_Project_work_using_git. You can also read the Git Community Guide from the git project themselves here, http://book.git-scm.com

What do I need to configure in git to work with documents?

Read this wiki page from the Docs Project on using git, Docs_Project_work_using_git.

What basic commands to I need to know to use git?

These are the four commands that will get you working with the Docs Project:

  • git clone

Creates a copy of the git repository on your computer.

  • git add

Tells git that it should pay attention to a file you have changed or added.

  • git commit

Tells git that you are serious about the group of changes you have "added". You need to provide a description of your change. Unlike other version control systems, git lets you commit a group of files at one time, which normally is more meaningful.

  • git push

Pushes your local commits to the big repository in the sky. You need to be part of the commit group for the repository to do this.

How do I build a document using publican?

What is publican?

Who is the Docs Project Leader?

The Docs Project Leader is Eric Christensen

Where is the best place to get immediate help?

How do I know what "branch" to use when editing a doc? Will someone tell me exactly which one to use?

Here's the basic idea: 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. Typically that branch is "F-12" or some such. 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, also, we don't support (fix) docs that are tied to a release of Fedora that is no longer supported.

Also can I just follow the git wiki commands to do that stuff?

The git guide on the wiki has most of the commands you need, I think.

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?

Are they all a fix for one bug report? if so, one commit is fine. One per bug report is a good measure, another example of where to split: if you make big structure changes, do those first and commit, then do content changes (clean-up, typos, etc.) as a second commit, it makes it easier for others to review the work and see the impact. 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.


What is the proper etiquette for fixing bugs or making changes in documents?

You can put a note in the bug report that you'd like to fix it, or go ahead and show the fix. If you've been given commit rights to the doc repository by the doc owner 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. you can note in the bug report that you made a commit (link) and think it fixes the bug., if so, please close. of course, if you keep doing that, you'll end up with bugs assigned to you :) remember -- source control management means never having to say you are sorry, if your fix doesn't work, it can be backed out, or more likely, just tweaked in the next commit.

Where can I learn about the open source world?

teachingopensource.org 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> one nice thing about IRC is the asynchronous nature of it, I leave my client running all the time in a way I can detach from, so if you ask questions or comment, I see it later and reply, we have discussions that span timezones and never even be together in the channel at the same time.

<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> You think we could do a new contributor FAQ type thing??



<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!


> 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



> 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.

--McD

Read First