Docs Project work using git

From FedoraProject

(Difference between revisions)
Jump to: navigation, search
m (Changed the category.)
(Don't use the '-a' flag, it commits *all* changes in files git knows about)
 
(14 intermediate revisions by 3 users not shown)
Line 3: Line 3:
 
You can help maintain content on the wiki, but it is also helpful to know how to make changes in this repository as well.  The following guide will show you, step by step, how to do that.
 
You can help maintain content on the wiki, but it is also helpful to know how to make changes in this repository as well.  The following guide will show you, step by step, how to do that.
  
= Setting Up =
+
== Setting Up ==
 +
 
 +
{{Admon/note | Account requirements | If you are working directly with Docs team contributors and want to push your changes into the repository, you'll need to have the following steps completed:
 +
* An account in the Fedora Account System (FAS), with a completed CLA and an uploaded RSA-type SSH public key ([[Account_System/NewAccount|instructions for FAS]])
 +
* Approved membership in the [https://admin.fedoraproject.org/accounts/group/view/docs-writers docs-writers] FAS group}}
 +
 
 +
You must install the <code>git-all</code> and <code>publican-fedora</code> packages  to use this project.  For some older systems like RHEL or CentOS 5, you may need to use <code>git</code> instead of <code>git-all</code>.
  
{{Admon/important | Install packages | You must install the <code>git-all</code> and <code>publican-fedora</code> packages  to use this project.  For some older systems like RHEL or CentOS 5, you may need to use <code>git</code> instead of <code>git-all</code>.}}
 
 
Install the <code>git-all</code> and <code>publican-fedora</code> packages with <code>yum</code>:
 
Install the <code>git-all</code> and <code>publican-fedora</code> packages with <code>yum</code>:
 
<pre>
 
<pre>
Line 17: Line 22:
 
git config --global color.branch auto</pre>
 
git config --global color.branch auto</pre>
  
= Getting a Copy of the Files =
+
== Getting a Copy of the Files ==
  
 
To get a copy of a module, in this example the <code>install-guide</code> project for the source of the ''Fedora Installation Guide'':
 
To get a copy of a module, in this example the <code>install-guide</code> project for the source of the ''Fedora Installation Guide'':
Line 27: Line 32:
 
A copy of the files from this repository are now in the <code>install-guide</code> directory in your current working directory.
 
A copy of the files from this repository are now in the <code>install-guide</code> directory in your current working directory.
  
{{Admon/note | Locally or remotely writable | The <code>git</code> command above produces a repository where you can make changes locally, but not back at the remote source (origin).  If you're a user of this repository authorized to write changes, use <code>git+ssh://</code>  instead of <code>git://</code> in the <code>git clone</code> command above.}}
+
{{Admon/note | Locally or remotely writable | The <code>git</code> command above produces a repository where you can make changes locally, but not back at the remote source (origin).  If you're a user of this repository authorized to write changes, use <code>ssh://</code>  instead of <code>git://</code> in the <code>git clone</code> command above. In general using <code>ssh://</code> could be useful (as a global setting), add to the local ~/.ssh/config file:
 +
* Host *.fedorahosted.org fedorapeople.org
 +
* User ''your_FAS_account-name''
 +
''fedorapeople.org is optional''
 +
}}
  
= Using the Right Branch =
+
== Using the Right Branch ==
  
 
We use <code>git</code> branches to separate releases of any guides that are tied to specific Fedora releases.  For instance, the Installation Guide has multiple active versions at any one time.  Right now, those versions are {{FedoraVersion||previous}}, {{FedoraVersion}}, and {{FedoraVersion||next}}.  (Releases for {{FedoraVersion|long|next}} will be on the main or "master" branch.)
 
We use <code>git</code> branches to separate releases of any guides that are tied to specific Fedora releases.  For instance, the Installation Guide has multiple active versions at any one time.  Right now, those versions are {{FedoraVersion||previous}}, {{FedoraVersion}}, and {{FedoraVersion||next}}.  (Releases for {{FedoraVersion|long|next}} will be on the main or "master" branch.)
 +
 +
To see all the available branches from the origin, do this:
 +
<pre>git branch -r</pre>
 +
You'll see a list that may look like this:
 +
origin/HEAD
 +
origin/f{{FedoraVersion||previous}}
 +
origin/f{{FedoraVersion}}
 +
origin/master
  
 
''Before you start working'', make sure you are on the proper branch (''f{{FedoraVersion||previous}}'', ''f{{FedoraVersion}}'', or ''master'') using one of these commands:
 
''Before you start working'', make sure you are on the proper branch (''f{{FedoraVersion||previous}}'', ''f{{FedoraVersion}}'', or ''master'') using one of these commands:
 
<pre>cd install-guide
 
<pre>cd install-guide
git checkout <branch></pre>
+
git checkout -b <branch> --track <originbranch></pre>
 +
So if you want to work on the ''f{{FedoraVersion}}'' branch, use this command:
 +
git checkout -b f{{FedoraVersion}} --track origin/f{{FedoraVersion}}
  
= Making Changes =
+
== Making Changes ==
  
 +
=== Make a personal branch ===
 
The <code>git</code> application uses ''branches'' in a novel way, to allow you to keep your work separated from the files that you just retrieved.  You should always make a branch of the files and do your work there.  Then after you've done appropriate testing, you can merge those changes into the branch you retrieved and send them to the maintainers via email, or (if you have access) push them back to the repository here.
 
The <code>git</code> application uses ''branches'' in a novel way, to allow you to keep your work separated from the files that you just retrieved.  You should always make a branch of the files and do your work there.  Then after you've done appropriate testing, you can merge those changes into the branch you retrieved and send them to the maintainers via email, or (if you have access) push them back to the repository here.
  
Line 48: Line 68:
 
<pre>git branch</pre>
 
<pre>git branch</pre>
  
 +
=== Make changes ===
 
Now make a desired change.  Remember that you don't want to make a bunch of changes at one time -- make one meaningful change (like cleaning up one file, or cleaning up one issue that happens in a number of files) at a time.
 
Now make a desired change.  Remember that you don't want to make a bunch of changes at one time -- make one meaningful change (like cleaning up one file, or cleaning up one issue that happens in a number of files) at a time.
  
To check the status of your branch (how it differs from the last recorded change), run the <code>git status</code> command.  If you need to add or delete files, use the <code>git add</code> or <code>git rm</code> commands.  To rename or relocate a file, use the <code>git mv</code> command.
+
To check the status of your branch (how it differs from the last recorded change), run the <code>git status</code> command.  If you need to delete files, use the <code>git rm</code> command.  To rename or relocate a file, use the <code>git mv</code> command.
  
Once you've finished making a meaningful change, ''commit'' it.
+
Once you have finished with all the changes, ''DOUBLE CHECK THEM!'' Don't go any further until the changes you made to the Release Notes produce a fully working document. Run a validation test to check (this example is using the original "en-US" language):
<pre>git commit -a -m 'Some short message about the commit'</pre>
+
<pre>publican build --formats=xml --langs=en-US</pre>
  
The commit goes to your local branch, not back up to the server as in some other version control systems.
+
=== Stage the changes ===
 +
The <code>git add</code> command tells git that it should ''stage'' specific changes you make.  Staged changes are the changes that will be recorded in the next commit.  You can stage changes from more than one file at a time, but you should make sure these changes are related.  Don't stage changes together that have nothing to do with each other. It's OK to make several commits, and usually a better idea to do so if you're unsure.
 +
<pre>git add en-US/my-changed-file1 en-US/my-changed-file2</pre>
  
Once you have finished with all the changes, ''DOUBLE CHECK THEM!'' Don't go any further until the changes you made to the Release Notes produce a fully working document. Run a validation test to check (this example is using the original "en_US" language):
+
=== Commit the changes ===
<pre>make validate-xml-en_US</pre>
+
Once you're ready to commit your changes, use the <code>git commit</code> command.
 +
<pre>git commit -m 'Some short message about the commit'</pre>
  
= Sending Back Changes (Unauthorized Version) =
+
The commit goes to your local branch, not back up to the server as in some other version control systems.
 +
 
 +
== Sending changes if you're not authorized ==
  
 
If everything works, you can email your changes back to the maintainers even if you're not authorized to write to the repository:
 
If everything works, you can email your changes back to the maintainers even if you're not authorized to write to the repository:
<pre>git-format-patch -o /tmp/mywork origin</pre>
+
<pre>git format-patch -o /tmp/mywork origin</pre>
  
 
This puts a series of patch files in the new directory <code>/tmp/mywork</code>.  Then you can email those patch files to [mailto:fedora-docs-list@redhat.com the maintainers].
 
This puts a series of patch files in the new directory <code>/tmp/mywork</code>.  Then you can email those patch files to [mailto:fedora-docs-list@redhat.com the maintainers].
  
 +
== Merging and pushing if you're authorized ==
 +
 +
{{Admon/important | Test before pushing! | Always test your changes before pushing them back to the remote official repository.  Use <code>publican build --formats=xml --langs=en-US</code> or some other XML validating command first. }}
 +
 +
If you mistakenly used <code>git://</code> for cloning instead of <code>ssh://</code>, you can fix that by editing the <code>.git/config</code> file before pushing.  Look for the "origin" section and edit the URL, replacing <code>git://</code> with <code>ssh://</code>.
 +
 +
{{Admon/note | From the author | These procedures are very basic and some usage may differ from project to project.  Check with the project owner if you have any doubts, or just send email instead.  Refer to [[#Sending changes if you're not authorized]] for more information.}}
 +
 +
=== Merging ===
 +
Switch from your private branch to the branch you are working in, most likely master
  
= Merging and Pushing (Authorized Version) =
+
git checkout master
  
{{Admon/important | Test before pushing! | Always test your changes before pushing them back to the remote official repository.  Use <code>make validate-en-US</code> or some other XML validating command first. }}
+
Merge the changes from your private branch (named 'mywork' in this case) to master:
  
If you're authorized, you can send your commits back to the repository. To push the results up to the repository here at Fedora Hosted:
+
  git merge mywork
<pre>git push origin master</pre>
+
  
If you mistakenly used <code>git://</code> for cloning instead of <code>git+ssh://</code>, you can fix that by editing the <code>.git/config</code> file before pushing.
+
=== Pushing ===
 +
You should be able to push your changes to the remote repository by running:  
  
{{Admon/note | From the author | I'm just learning <code>git</code>, so the use of the ''master'' branch above may not be the best practice. Input gratefully accepted from more experienced <code>git</code> users.}}
+
  git push
  
= Other References =
+
== Other References ==
  
 +
* http://book.git-scm.com -- the best user-friendly git documentation, from the git project itself
 
* http://www.gitcasts.com
 
* http://www.gitcasts.com
 
* http://excess.org/article/2008/07/ogre-git-tutorial/ -- complete tutorial that includes an explanation of SCM (source code management)
 
* http://excess.org/article/2008/07/ogre-git-tutorial/ -- complete tutorial that includes an explanation of SCM (source code management)
  
 
[[Category:Documentation tools]]
 
[[Category:Documentation tools]]
 +
[[Category:How to]]

Latest revision as of 16:50, 18 October 2011

The Documentation Project produces documentation written in DocBook XML. Earlier documentation used a CVS instance for collaboration. The DocBook XML files are now maintained in git repositories, which provide better features and future proofing. DocBook XML documentation can be built into HTML and other formats for use on the Web and in Fedora itself.

You can help maintain content on the wiki, but it is also helpful to know how to make changes in this repository as well. The following guide will show you, step by step, how to do that.

Contents

[edit] Setting Up

Note.png
Account requirements
If you are working directly with Docs team contributors and want to push your changes into the repository, you'll need to have the following steps completed:
  • An account in the Fedora Account System (FAS), with a completed CLA and an uploaded RSA-type SSH public key (instructions for FAS)
  • Approved membership in the docs-writers FAS group

You must install the git-all and publican-fedora packages to use this project. For some older systems like RHEL or CentOS 5, you may need to use git instead of git-all.

Install the git-all and publican-fedora packages with yum:

su -c 'yum install git-all publican-fedora'

Create your global git configuration:

git config --global user.name 'John Doe'
git config --global user.email 'jdoe@example.com'
git config --global color.diff auto
git config --global color.status auto
git config --global color.branch auto

[edit] Getting a Copy of the Files

To get a copy of a module, in this example the install-guide project for the source of the Fedora Installation Guide:

mkdir projects
cd projects
git clone git://git.fedorahosted.org/git/docs/install-guide.git

A copy of the files from this repository are now in the install-guide directory in your current working directory.

Note.png
Locally or remotely writable
The git command above produces a repository where you can make changes locally, but not back at the remote source (origin). If you're a user of this repository authorized to write changes, use ssh:// instead of git:// in the git clone command above. In general using ssh:// could be useful (as a global setting), add to the local ~/.ssh/config file:
  • Host *.fedorahosted.org fedorapeople.org
  • User your_FAS_account-name
fedorapeople.org is optional

[edit] Using the Right Branch

We use git branches to separate releases of any guides that are tied to specific Fedora releases. For instance, the Installation Guide has multiple active versions at any one time. Right now, those versions are 19, 20, and 21. (Releases for Fedora 21 will be on the main or "master" branch.)

To see all the available branches from the origin, do this:

git branch -r

You'll see a list that may look like this:

origin/HEAD
origin/f19
origin/f20
origin/master

Before you start working, make sure you are on the proper branch (f19, f20, or master) using one of these commands:

cd install-guide
git checkout -b <branch> --track <originbranch>

So if you want to work on the f20 branch, use this command:

git checkout -b f20 --track origin/f20

[edit] Making Changes

[edit] Make a personal branch

The git application uses branches in a novel way, to allow you to keep your work separated from the files that you just retrieved. You should always make a branch of the files and do your work there. Then after you've done appropriate testing, you can merge those changes into the branch you retrieved and send them to the maintainers via email, or (if you have access) push them back to the repository here.

First, make a branch called "mywork" and move onto it to do your actual work:

cd install-guide
git checkout -b mywork

(Note this doesn't retrieve files, it puts you on the new mywork branch you created. To check that you've moved branches, you can use the git branch command again:

git branch

[edit] Make changes

Now make a desired change. Remember that you don't want to make a bunch of changes at one time -- make one meaningful change (like cleaning up one file, or cleaning up one issue that happens in a number of files) at a time.

To check the status of your branch (how it differs from the last recorded change), run the git status command. If you need to delete files, use the git rm command. To rename or relocate a file, use the git mv command.

Once you have finished with all the changes, DOUBLE CHECK THEM! Don't go any further until the changes you made to the Release Notes produce a fully working document. Run a validation test to check (this example is using the original "en-US" language):

publican build --formats=xml --langs=en-US

[edit] Stage the changes

The git add command tells git that it should stage specific changes you make. Staged changes are the changes that will be recorded in the next commit. You can stage changes from more than one file at a time, but you should make sure these changes are related. Don't stage changes together that have nothing to do with each other. It's OK to make several commits, and usually a better idea to do so if you're unsure.

git add en-US/my-changed-file1 en-US/my-changed-file2

[edit] Commit the changes

Once you're ready to commit your changes, use the git commit command.

git commit -m 'Some short message about the commit'

The commit goes to your local branch, not back up to the server as in some other version control systems.

[edit] Sending changes if you're not authorized

If everything works, you can email your changes back to the maintainers even if you're not authorized to write to the repository:

git format-patch -o /tmp/mywork origin

This puts a series of patch files in the new directory /tmp/mywork. Then you can email those patch files to the maintainers.

[edit] Merging and pushing if you're authorized

Important.png
Test before pushing!

If you mistakenly used git:// for cloning instead of ssh://, you can fix that by editing the .git/config file before pushing. Look for the "origin" section and edit the URL, replacing git:// with ssh://.

Note.png
From the author
These procedures are very basic and some usage may differ from project to project. Check with the project owner if you have any doubts, or just send email instead. Refer to #Sending changes if you're not authorized for more information.

[edit] Merging

Switch from your private branch to the branch you are working in, most likely master

git checkout master

Merge the changes from your private branch (named 'mywork' in this case) to master:

git merge mywork

[edit] Pushing

You should be able to push your changes to the remote repository by running:

git push

[edit] Other References