Projects - Cooperation and Arch
Projects - Cooperation and Arch
This document covers merging and requesting for your changes to be merged into the archives of others.
[ Top: Arch Tutorial ]
[ Previous is Part 2: Developing With Arch ]
[ This is Part 3: Cooperation and Arch ]
[ Next is Part 4: Arch Resources ]
I'm assuming that you have already registered the archives of other people. Let's say that you've made some changes to someone else's project and want to know where to go from there. I'm assuming that you have already made your own branch of the project and have committed a few changes.
M-x tla-name-of-command will usually work.
Substitute "name-of-command" for the particular tla command that you
want to do. If you're anxious to know what the short keypress
sequence is for each of these commands, type C-h m in an DVC-related
buffer and look for them.I prefer to keep a copy of the original project's source tree around.
Then whenever I want to check for updates, all I have to do is move to
their directory and replay their changes with the tla replay
command.
If you are in your own project's source tree and want to quickly check for changes, do something like the following. The third argument specifies the other source tree to check.
tla changes mwolson@member.gnu.org--2005/emacs-wiki--main--1.0
tla
update, Arch will save any local changes that you have made, replay
any missing patches, and then restore your changes.tla replay will only replay any missing patches. Thus,
if it encounters a conflict, further invocations of tla replay
will fail until you have cleaned up the mess.You made a few commits to your branch of a project. But when you take a look at the project you follow, they have committed a few more changes. How do you reconcile your branch with theirs?
The most oft-recommended method for reconciling changes is the use of
tla's star-merge command. To make use of it, change into
the top level directory of your source tree and do the following.
Don't worry, it won't commit any changes it makes quite yet.
tla star-merge --three-way \
other@project.org--2005/proj-name--branch--1.0
The third argument determines which project to pull changes from. You can pull in changes up to a particular patch number by doing something like the following. Note that "—patch-5" is appended to the full branch name.
tla star-merge --three-way \
other@project.org--2005/proj-name--branch--1.0--patch-5
If you need to see the options for this command , type tla
star-merge --help.
If there are any conflicts that occur between the source trees and the
changes do not apply cleanly, reject files will be generated. These
files have an extension of .rej. The original file will be copied
with an extension of .orig. The file itself will have regions which
look something like the following example.
<<<<<<< ... new code ... ============================ ... old code ... >>>>>>>
It is best to modify the file and merge the differences manually.
When you are done, remove the .orig and .rej files.
This step should be taken once you feel ready to commit your changes and merges into your repository.
tla make-log or C-x T c. If you
do this in DVC, save the log file now.tla log-for-merge >> ++name-of-log-file
This will indicate to you and your developers which patches have been merged. Arch itself does not require the log file to have this information, but it is good practice nonetheless.
tla commit or
C-c C-c while viewing the log buffer in xlta.If you have write access to a shared Arch archive, but have your own private branch, you may want to merge your changes back to the shared Arch archive.
To do this, follow the instructions in the previous chapter (Merging
new changes from another source), but change to the directory of the
shared Arch branch, and pass the name of your repository to the tla
star-merge command.
If you only want to merge certain changes rather than all of them,
change to the directory of the shared Arch and pass the full name of a
patch to tla replay. The following example does this, assuming that
the name of your archive is my@archive.org--2006 and the name of the
branch is my-project--janedoe--0, and that the name of the patch is
patch-3.
tla replay my@archive.org--2006/my-project--janedoe--0--patch-3
After merging your changes into the directory for the shared Arch
branch, don't forget to run tla commit with a proper log message in
order to finalize your changes.
I highly recommend doing your development on an archive that is on your own computer. This section will show you how to set up a mirror of your archive that can be accessed by others, as well as how to do things without a mirror.
If you want to host an archive directly on a webserver without a local
mirror, you will need to cause .listing files to be generated in
order for others to be able to use your archive.
As odd as it seems, you need to create a file called http-blows in
your =meta-info directory.
touch /path/to/archives/my@archive.org--2005/=meta-info/http-blows tla archive-fixup my@archive.org--2005
Arch should automatically update the .listing files from that point
on whenever you commit a change.
If you have a way of publishing documents to a web server, you can skip this sub-section.
I recommend taking a look at http://gna.org. They seem to offer Arch support.
If your web machine is unreliable, think about getting a mirror. http://www.sourcecontrol.net/ would be a good start. Note that you must have an HTTP-accessible location for your archive before getting an account there.
Arch needs to know the location of this mirror. To provide it with this information, do the following. The second-to-last argument is the name of your archive. The last argument is the remote location where the mirror will be stored.
tla make-archive --listing --mirror my@archive.org--2005 \
sftp://login@machine.com/path/to/www-root/archives/2005
The --listing option makes sure that the contents of your archive
can be accessed with the HTTP access method. If in doubt, use it.
Any time you want to bring your local archive up-to-date with the mirror, perform the following command. Give the name of your archive for the last argument.
tla archive-mirror my@archive.org--2005
If you are prone to forget things (like me), you might want to automate this step by including it in whatever routine you use to update your website.
This is something that you have to decide for yourself. If I made a patch for a project, I would probably check for the existence of a mailing list first. If that fails, pick the developer who seems the most involved, I guess.
You might want to make a convincing argument for the inclusion of your patch if you believe your patch to be necessary.
Your subject line could look something like this.
[merge request] Make font-locking significantly faster in emacs-wiki
If the project uses Arch, the easiest thing would be to send an email message with the location of your archive, patches to pull, and a description of your changes. An example letter is in the next sub-section.
If the project does not use Arch primarily, you might want to send in
a patch. Executing the diff command as follows will probably be
sufficient. A new file called "desc-of-patch.diff" will be created —
change this to be a few short keywords linked together with a "-" or a
"_" character.
diff -u their-project-dir your-project-dir > desc-of-patch.diff
You might want to consider adding the -b and
-w options to diff if you do not want
whitespace and indentation changes to appear. This makes the patch a
bit smaller and more easily understandable.
I am not the kind of guy who uses salutations or special closing statements, but you are welcome to use them here.
From: Your Name <a_valid_email@address.com> To: emacs-wiki-discuss@nongnu.org Subject: [merge request] Fix a few font-lock issues in emacs-wiki Archive: my@archive.com--2005 Branch: =emacs-wiki--myname--1.0= Location: http://www.mywebsite.com/archives/2005 Patches: 3-6 I have made the following changes to emacs-wiki and would like for them to be included in the next emacs-wiki release. Please merge patch-3 through patch-6 from my archive. - Improve font-locking by setting the foo tag to nil. - Add documentation to Wiki Markup section. - Fix race condition when user types M-x foo. - Do not put <p></p> tags around <form>.
[ Previous is Part 2: Developing With Arch ]
[ This is Part 3: Cooperation and Arch ]
[ Next is Part 4: Arch Resources ]
![[FSF Associate Member]](/static/logos/fsf-member.png)
