Sugar Labs - User contributions [en]

Activity Team/Git Tutorial

2010-12-30T23:33:53Z

Abhunkin: /* Other Notes */

<noinclude>{{GoogleTrans-en}}{{TeamHeader|Activity Team}}{{TOCright}}</noinclude>

== Gitorious ==

Getting started with Gitorious, a web based Git service provided by Sugar Labs.

You will learn to:
* create an account, which you do once,
* create and add an SSH key, which you do once or if you change system,
* create a project, a local repository, and identify yourself to git, which you do once per project,
* add source files, change existing source files, commit changes, push changes, and pull changes, which you do regularly.

=== Create an Account ===

Create an account on git.sugarlabs.org by selecting the ''Register'' link on the page. You will be asked:
*Login
*Email
*Password
*Password Confirmation

Fill the fields and press ''SIGN UP''. Gitorious will send you a confirmation email. Check your email, wait for the confirmation, and follow the link provided.

Once you do this, Gitorious knows who you are and how to contact you. You should only need to do this once.

You'll need to login to Gitorious whenever you want to do any of the actions described here.

=== Create SSH Key ===

Skip this section if you already have an SSH key in <tt>.ssh</tt> directory that you trust.

To create a key use ''ssh-keygen''. The following command will create a “dsa” key:
ssh-keygen -t dsa

For creating a “rsa” key use:
ssh-keygen -t rsa

The key will be stored as two files in the hidden <tt>.ssh</tt> directory.

<tt>id_dsa.pub</tt> is your public key. <tt>id_dsa</tt> is your private key. Only you should have access to this private key. Access to the key will grant access to Gitorious in your name. For example, here is a list of files in the <tt>.ssh</tt> directory of user strom:
ls -al ~/.ssh
-rw------- 1 strom strom 668 2009-12-17 21:51 id_dsa
-rw-r--r-- 1 strom strom 603 2009-12-17 21:51 id_dsa.pub

You should only need to create a key once, unless you change to another system, or you think your private key was compromised. (Note that "change to another system" includes each new Sugar-on-a-Stick USB drive.) If you do it again, you must also add the new key to Gitorious as described in the next section.

=== Add SSH Key ===

Log in to http://git.sugarlabs.org/ click on ''Dashboard'', then ''Manage SSH'', then ''Add SSH key''. The ''Add a new public SSH key'' page will appear, with a large text entry field. Open your public key in a text editor or web browser (or display it with the cat command), and then paste it into the text entry field. Click on ''Save''.

Once you do this, Gitorious trusts SSH connection from your system because your system has the private key, and Gitorious has the public key. You should only need to do this once, unless you change to another system.

(With ssh-keygen you can specify the name of your key file. Using this feature is not a good idea, because we haven't tested it. Keys should generally be located in <tt>~/.ssh/id_rsa.pub</tt> or <tt>~/.ssh/id_dsa.pub</tt>.)

ToDo: Do keys protected with a passphrase work together with GIT?

ToDo: What is the difference between DSA and RSA keys?
* until the patent expired, RSA could not be used in some countries,
* some countries have laws against consumer use of encryption.

=== Create a Project ===

Check that the activity is not already on git.sugarlabs.org. If it is, note the clone URL and skip to the next section. If it is not, then click the ''Create a new project'' link on the ''Projects'' page, and enter:
*Title
*Slug (this defaults to a file name format of your title; it consists of your title without caps, and with non-alphanumeric characters replaced by dashes)
*License (this is the same as the one described at the beginning of your primary python file)
*Description
then click on ''Create project''. There several other question which can be answered later as you have more information.

Once this step is done, Gitorious will have created a git repository at Sugar Labs. You must only do this once for each project.

=== Create Local Repository ===

Clone it from Gitorious:
git clone gitorious@git.sugarlabs.org:${SLUG}/mainline.git ${SLUG}.git

Replace the ''${SLUG}'' substring with your project slug value. Your local repository (folder) is now named <your-slug-name>.git

Once you do this, you will have a local repository that shares the same history of changes (if any) of the repository at Sugar Labs. You should only need to do this once for each project and system. You can do it again if you need a fresh copy that has no changes.

=== Identify Yourself to Git ===

Git on your local system must know your email and name. It uses this when you commit a change, so that when you push or mail it others will know who did it.

If you do not use git on your system for any other project, you can configure git:

git config -f ~/.gitconfig user.email <email-you-used-for-registering-project>
git config -f ~/.gitconfig user.name <your-name>

You should only need to do this once on a system.

Otherwise, configure git in the repository:

cd <your-slug-name>.git
git config user.email <email-you-used-for-registering-project>
git config user.name <your-name>

You should only need to do this once in a repository.

=== Develop ===

Use a text editor or integrated development environment to create new source files or change existing files. Test the results by running the activity. Do this from your local repository, or from elsewhere - then copy your files to the repository. Repeat until you are satisfied with the changes you made.

=== Commit Changes ===

Always in your local repository, find out from git what files you changed:
git status

Add any files that are new or changed:
git add ...

Tell git to collect the changes into a commit:
git commit

You should do this for every meaningful set of changes you make.

=== Request Review ===

Before you publish changes widely, you can ask others to review your work and comment on it.

git format-patch -1

or

git send-email

You may do this for every set of changes you make.

=== Push Changes ===

Your changes have to be pushed from your local repository to the repository at git.sugarlabs.org so that others can see them there.

git push

You must do this for every set of changes you make, when you want to synchronise with other developers or prepare for a release.

=== Pull Changes ===

Others, including pootle, may add changes to the repository at git.sugarlabs.org. You must merge these with your repository.

Use
git-pull

Also, run
python setup.py fix_manifest
to update the .mo files after updating the .po files

You should do ''git pull'' frequently; before starting development, before pushing changes, and when you see other developers commit changes.

=== For Further Information ===

There is an excellent chapter (chapter 11) on Git in the "Make Your Own Sugar
Activities!" Floss manual by James Simmons: http://objavi.flossmanuals.net/books/ActivitiesGuideSugar-en-2010.08.30-15.48.49.pdf
It is highly recommended for intermediate and advanced users.

== Other Notes ==

=== Tags ===

alsroot taught me about another git feature: tags

git tag -m "Release 36" v36 HEAD
git push --tags

=== What Pull Does ===

bertf explained to me that git-pull does a combination of fetch and merge, so to merge a patch...

git pull git://git.sugarlabs.org/infoslicer/alsroots-clone.git master

[[Category:Activity Team]]
[[Category:HowTo]]

Activity Team/Git Tutorial

2010-12-30T23:30:50Z

Abhunkin: /* Gitorious */

Activity Team/Object Chooser

2010-12-27T22:11:11Z

Abhunkin: /* The Sugar Object Chooser */

== The Sugar Object Chooser ==

The following example is modified from the FileMix activity. Note that it invokes the Chooser to select objects of mime type GENERIC_TYPE_AUDIO.

from sugar.graphics.objectchooser import ObjectChooser
from sugar import mime

self.path = "0"
self.jobject = None

# Determine which version of Sugar you are running
try:
from jarabe import config
version = [int(i) for i in config.version.split('.')][:2]
except ImportError:
version = [0, 82]

if version >= [0, 84]:
# Insert here code relevant to Sugar 0.84 and higher
# I use this to only display Object Chooser callback buttons only for >= 0.84
# Clicking one of the displayed buttons calls the choose method

def choose(self, widget):
chooser = ObjectChooser(parent=self, what_filter=mime.GENERIC_TYPE_AUDIO)
result = chooser.run()
if result == gtk.RESPONSE_ACCEPT:
self.jobject = chooser.get_selected_object()
self.path = str(self.jobject.get_file_path())
else:
self.jobject = None
self.path = "0"

=== Random observations: ===

# I exclude Sugar 0.82 for two reasons (which means, unfortunately, "no user soundfiles for 0.82"):
#* its version of Object Chooser does not allow filtering for the audio mime type;
#* Sugar 0.82's Csound (5.08) - or more specifically its version of libsndfile - does not handle ogg vorbis soundfiles, the type that the Record activity (later versions) creates. Record is the most likely/accessible means that children would use to create their own soundfiles. (The whole idea behind using Object Chooser here is to select user files that have been placed in the Journal [as Record does by default] for performance in FileMix.)
#* In addition, '''earlier''' versions of Record (<v76, except for v61-64) create ogg '''speex''' soundfiles; even the recent versions of Csound (actually, libsndfile) do not handle this (lo-fi) format. (Unfortunately, ''no'' versions of Record [as of 12/10] produce any audio, ''except'' ogg speex, in Sugar > 0.84.)
# self.path stores the soundfile name (complete path); self.jobject stores the object itself. This is key to being able (in Csound) to locate and load the selected soundfile. self.path is then a channel opened to send the named soundfile to Csound.
# If the user closes the Object Chooser box instead of clicking on a sound object, the result is not accepted, and self.path reverts to "0" - which is a flag (in Csound) to revert to the default soundfile included in FileMix.
# The str() cast for self.path converts the filename to the usual path format readable by Csound (this too is required). Otherwise, the file_path is a dbus string object; maybe we need to cast this type in sugar-toolkit code (though in most cases this casting should happen implicitly).

The above code is included in FileMix-4.xo, in filemix.py (where there are 4 Object Chooser methods triggered by 4 callback buttons). Source for this activity has been made visible online.

''Art Hunkins and Aleksey Lim''