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:
ui
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,
-
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.
-
Make your changes on your copy, using your IDE or editor
of choice.
-
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.
-
Commit your changes locally with
hg commit -m "your commit message".
-
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!