Overview¶
Sympa is live on the server parrot.riseup.net, its running out of /home/sympa, using apache2. (Currently this is not a subversion checkout of the development version, but it will be).
Development of fixes, changes, etc. to sympa happens on the development instance: stilt.riseup.net. Once everything is to our satisfaction on stilt, then things are checked into subversion and then it can be checked out on the live server.
Where it all happens¶
Riseup sympa development happens in /home/sympa/riseup. Here you can find the upstream original source (subversion checkouts of specific release tags using svn externals) and a patches directory which contains the specific patches to the upstream sources that we have made. Lets talk about each individually and then describe the specific steps involved in the development cycle.
The patches directory¶
First, the /home/sympa/riseup/patches directory contains unified context diffs at level -p0 that apply to particular versions of sympa. The /home/sympa/riseup/patches/README details what each patch is for. Each of these patches have been adapted to work with the version of sympa the directory is named after. They are in a particular chronological order as many patches change files that later patches also change. As such, they must be applied in the order that they are named (for example 01_add_Sender_header.diff must be applied before 02_cache-list-configs.diff etc.). These patches should be submitted upstream, if they haven’t been already, so that we do not need to carry these deltas from the upstream source forwards.
The upstream source¶
Secondly, the /home/sympa/src/sympa-x.×.x directories are svn checkouts of the upstream tagged version represented by the directory name. This is done through the ‘svn externals’ mechanism, which allow us to pull the upstream source into our repository so we can do our work. How this works is descrbed below. The sympa source directory is in a pre ‘make’ state, and will have local modifications to it because we will patch it. These differences from the upstream source will enable us to generate our individual diffs.
How to handle a new release¶
When a new release of sympa comes out, this src directory is updated to the newly tagged release, then the diffs in the patches directory are applied on top of this freshly checked out source, and any modifications are done at this time. The patches will need to be re-worked to apply to the new version.
The steps to do this are outlined below:
Get the latest sympa tagged release¶
1. First go into the /home/sympa/riseup/src directory and then update the externals property for the new release:
% cd /home/sympa/riseup/src
% svn propedit svn:externals .
2. Then change the tag version number and the repository version number to the new versions, if you are changing from 5.3.4 to 5.4 simply change it to look as follows:
sympa-5.4 http://subversion.cru.fr/sympa/tags/sympa-5.4
3. Then remove the old tag and check out the new one, in our example we are upgrading from 5.3.4 to 5.4:
% rm -rf sympa-5.3.4
% svn up
4. Then create a new patches version directory for the version we are going to be moving to (in this case 5.4):
% svn mkdir /home/sympa/riseup/patches/5.4
Now in /home/sympa/riseup/src there will exist a sympa-5.4 directory which is a checkout of the upstream repository and there will be a /home/sympa/riseup/patches/5.4 directory which will be empty. We need to populate that new patches directory with the previous version’s patches, but reworked for this new version.
Rework the patches to apply to the new version¶
To do this, step through each patch (in chronological order) from the previous version and get it to apply to the new version of sympa.
1. First attempt a dry-run patch of the previous version’s patches. Notice below that we are working on the new version of sympa (in our example this is 5.4) and attempting to do a dry-run patch of a patch we used for the previous version (in our example: 5.3.4:
% cd /home/sympa/riseup/src/sympa-5.4
% patch --dry-run -p0 < ../../patches/5.3.4/01_add_Sender_header.diff
If there are any Fuzz or reject lines, then open an editor and step through the diff and the file that it patches and reconcile these things. Save the new patch in the new version directory (don’t overwrite the original from the previous version!). Be sure to clean it up so there is no fuzz because the fuzz will gather over time and make next time harder.
2. Now that the patch has been re-worked, apply it to the source. You need to do this because the next patch you want to apply will require that the previous patch be applied.
Notice here that we are applying the newly re-worked patch that we saved in the patches/5.4 directory and are no longer using the 5.3.4 version of the patch:
% cd /home/sympa/riseup/src/sympa-5.4
% patch -p0 < ../../patches/5.4/01_add_Sender_header.diff
3. Now repeat this process until you have worked through all the patches in the previous version’s patches directory.
Hopefully over time we can reduce the deltas to the upstream source by pushing the changes upwards.
Check in your changes¶
Now that you have all the patches re-worked for the new version, you want to check in the changes:
% cd /home/sympa/riseup
% svn ci -m 'rework patches for new tagged release of sympa-5.4'
This will check in the new patches and the svn externals property change that you made earlier. Its better to check these both in at the same time so it is easier to associate the two in the repository history.
How to deploy our new version to the live server¶
Needs to be written!
Some notes:
need to talk about build process
need to take care about the archives, expl and spool directories
