display | more...

This is intended to be a quick guide in order to allow edevites to work with the currently running ecore and submit patches via Mercurial, hereafter simply "hg". As of this noding, the patches can go to me, but hopefully someone else can undertake this task later on as they become more comfortable with hg. This is also not meant to be a definitive guide. There's a whole book for that. This is just a few quick pointers to get you started.

First, make sure you understand what hg is and does.

The next step is to get it installed on your system so that you can work with it. In an apt-based system like Debian or Ubuntu, this should be as easy as "aptitude install mercurial" (make sure your sources are up to date beforehand). For Windows and MacOS X, you can download pre-built binaries here. Since hg is a primarily command-line driven program, you might find some comfort in the available GUI tools. TortoiseHG might be worth checking out. If you feel like experimenting, hgview also looks nice.

Once you're setup, you should modify your .hgrc (Unix-like) or Mercurial.ini (Windows) to identify yourself. Create the file if it doesn't exist, and add two lines like this:

  username = Bluepill Name <email@domain.com>
It's my habit when working on free projects' source trees to not use pseudonyms, but if you prefer to use a pseudonym instead of your bluepill name, go ahead. That name will identify the patches you submit to ecore.


In what follows I will describe the concepts from a purely command line interface point of view. The concepts are what are important; if typing at a prompt makes you uncomfortable, I imagine that TortoiseHG must have graphical methods to accomplish the same, but the important thing is to first get a basic understanding of how source control works.

The first thing you should do is get a local copy of the ecore repository on which you can work on with your locally installed tools. For this you have to clone from the ecore repository like so

hg clone http://hg.everything2.com/ecore
This will create a local directory named "ecore" from wherever you run this command that will have a snapshot of the source tree and all of its history up until that point. I should remark that ecore isn't very big, so this cloning should be really fast. If using TortoiseHG or another graphical frontend, you can run it from this source tree to get the directed acyclic graph representation of the repository up until this time. From the command line
hg log
will give dump you with the entire changelog of the project since I first committed after removing hardcoded passwords from the code. From a Unix-like system, you might want to pipe that to less so that you can read it (hg log | less) or on any system, you might want to just see a range of revisions, say from the 20th to the 30th revision, with hg log -r 20:30. Incidentally, all hg commands are documented with "help" so hg help log and hg help clone will give you more information about these commands. On most any modern installation of bash (which I believe all of MacOS X, Debian, and Ubuntu have) typing hg and hitting <TAB> will give you the list of all hg commands available which you can peruse with hg help $command.


Now that you're setup, your basic workflow will be like this,

  1. Update your working copy in case that that there have been changes since you last downloaded it with hg pull -u, which pulls from the remote repository and simultaneously updates your current copy with those changes it pulls.

  2. Make your changes on your copy, using your IDE or editor of choice.

  3. Review those changes either by the excellent integration that your editor has with hg, or by doing hg status to see which files you've modified and hg diff to get a thorough description of the changes you've made. In a Unix-like system you may want to pipe the result of these two operations to less so that you can actually read them.

  4. Commit your changes locally with hg commit -m "your commit message".

  5. If you have been given a user and password with which to push changes back into the main ecore repository, do hg push to do so, which will prompt you for your credentials. For now, I can give you a username and password with which you can push back changes. You can only commit changes, but not make them take effect; someone with shell access to the server still has to do that for you, so there's no real danger of giving widespread commit access.

    If you don't have or want a username and password for committing, you can export your patch with hg export -o some.patch tip assuming you only committed once, or hg export $r1 $r2 $r3 -o some.patch where $r1, $r2, $r3... are the revision numbers of your local changes (displayed by hg log or your GUI). Then email me or whomever's currently able to apply patches the file some.patch for inclusion into the main source tree.

That's basic usage and should be enough for starters. To summarise, clone first, then later (1) update, (2) modify, (3) review, (4) commit, (5) submit. I don't think for a quickstart you need to know too much about how to make branches and merge. You can read about that in the official book. For your own benefit and to ease your workflow, though, I am going to describe two other useful features, cloning and updating.

Cloning is something you do at the very beginning when working with a new repository, but it's something you can keep on doing once you have a local repository. The syntax is hg clone original_repo new_repo and all it does is create a new repository named new_repo that knows it was cloned from original_repo. This can be useful for a quick testing ground in case that you don't want to pollute your original repository tree with mistakes and invalid changes, and once you think you're done, you can move the changes back to the original one by running hg push from new_repo's root directory. If you have commit access to ecore, you can push your changes all the way back to e2.

Updating is being able to go back to any previous working revision of your code. You create revisions each time you run hg commit. You can see the revision number that you might want to go back to with hg log; in the changeset line, it's the number in front of the colon and before the gobbledygook (actually, a SHA-1 hash). When you do hg up (shorthand for hg update) this brings you to the latest revision, but you can go to any other revision in your changelog with hg up -r $revision_number. Note that if you're in an older revision, make changes, and commit those changes, you will have branched off at that revision, which in and of itself is ok. You'll still be able to export patches or push, but then that might involve a merge when committing those changes upstream. If you export the patch, then whoever applies the patch will be in charge of handling the merge; if you push yourself, then you'll be in charge of that merge. Try not to branch at first and keep the whole operation simple; think of updating to a previous revision just convenience for you so that you can see what the code looked like in a previous stage. If you forget at which revision you updated to, you can do hg id -n which will give you revision number at which you currently are.

That will do for now. I look forward to receiving your patches. Happy hacking!

Log in or register to write something here or to contact authors.