Rules to follow when using ImpressCMS SVN

Hi everyone, I would like to propose a few basic rules for all of us to follow when it comes to committing in the ImpressCMS SVN. This is a few rules I gattered from Dave_l post a few days ago.

1. Be informed of our discussions

Every developer need to stay informed of our discussions here. So we all need to make a commitment of reading everything that is posted on the Current and Future release forums. It is the only way we can all work together towards the same goal, and bringing synergy in our efforts.

2. Documenting our code

That means that every function has a phpDocumentor-compliant header comment, which is both correct and understandable, states the purpose of the function and describes the parameters and return value.

The same applies to class properties. The header comment for a function (or a class) is intended to be a "mini user manual" for the function that provides all the information needed to call that function, without having to examine the body of the function.

3. Use our trackers for nearly everything

Use the ImpressCMS trackers for everything you do. Bugs, Features, Tasks, everything.

For example, adding the Multilanguage features needs to have a task related. Same thing for the security audit or the removal of the XOOPS word all around.

4. Create 2-ways links

Create as many two-way links between Subversion changesets and ImpressCMS trackers as possible:

- In your commit message, refer to the tracker item ID.

- When you edit the tracker item on SourceForge, refer to the revision number of your commit in th SVN.

5. Commit logical changesets

When you commit a change to the repository, make sure your change reflects a single purpose: the fixing of a specific bug, the addition of a new feature, or some particular task. Your commit will create a new revision number which can forever be used as a "name" for the change.

6. About branching

We will use the "Branch-when-needed" system :

- Users commit their day-to-day work on /trunk.

- Rule #1: /trunk must compile and pass regression tests at all times. Committers who violate this rule are publically humiliated.

- Rule #2: a single commit (changeset) must not be so large so as to discourage peer-review.

- Rule #3: if rules #1 and #2 come into conflict (i.e. it's impossible to make a series of small commits without disrupting the trunk), then the user should create a branch and commit a series of smaller changesets there. This allows peer-review without disrupting the stability of /trunk.

Thoughts ?

Hi everyone, allow me to bring this discussion back. As we are welcoming more and more developers in the ImpressCMS SVN repository, it is important we all agree to a sets of rules.

These are the rules we have come up so far. As soon as our wiki will be opened, we will create a page for this there.

In the mean time,is anyone has some other thoughts on the subject ?

rule 4 - don't commit your personal mainfile

Regarding the approach of restricting the trunk to bug fixes, and using the 1.1 branch for new features...

I was reading Chapter 4: Branching and Merging of the SVN book. and it suggests a different approach: create a 1.0 branch, where bug fixes would be committed, and continue development in the trunk. After 1.0 final is released, and a 1.0 snapshot created in the tags directory, the 1.0 branch could be discarded.

I'm not sure which approach is better.

-----

Another point made in the SVN book: When merging (porting) changes from one branch to another, it's critical to note in the log the range of revisions merged. For example, "Merged xyz changes r341:405 into the trunk." If you don't record that info, you could wind up merging the same changes more than once, which could mess things up.

It seems like the approach Dave mentions can keep development momentum moving better. By creating a branch for an upcoming release, it is less likely to be altered by someone working in the trunk. We can continue to work in the trunk while the release candidate is tested and fixed before being released as final.

I like this approach better.

Also, for commonly edited files, like the changelog, update your sandbox copy and merge any other changes that have been commited - making reversions much cleaner.

Quote:

On this subject, I think we should publish our API documentation and make it available as soon as possible. There are some options to consider when doing this -
phpDocumentor - http://www.phpdoc.org/
phpxref - http://phpxref.sourceforge.net/
Doxygen - http://www.doxygen.org/

http://en.wikipedia.org/wiki/Comparison_of_documentation_generators

I also suggest we update this with every release

Doxygen is what Kris-fr has used recently... I've tried to use it, but can't quite follow it...

Quote:
I opened a new thread for this topic:
http://community.impresscms.org/modules/newbb/viewtopic.php?viewmode=flat&type=&topic_id=926&forum=55

Quote:
It is definitaly make much sens. Let's use this approach instead. I'll put all this in the wiki.

Quote:
Also agreed. Dave, did you see any recommendation on how to actually merge branches ? Shall we use Tortoise SVN merge feature or something else ? I think I remembered somewhere that it is a recommendation that merging should be done manually.

This is what I usually do, using BeyondCompare.

I just deleted branche imprescms_1.1 and copied the trunk in branches/impresscms_1.0.

So from now on, all bug fixes for 1.0 releases can be added in the impresscms_1.0 branch which we will merge over the trunk from time to time.

I will also update the other thread I started about this topic earlier this week and will document all this in the wiki.

Here you go:

http://wiki.impresscms.org/index.php?title=Using_SVN

Thanks Dave_l for helping us setting those rules.

Quote:

Chapter 4 of the SVN book has some examples. I haven't done any merging myself.

I've been using SVN from the command line so far, because it works the same in Windows and Linux, and it avoids having to deal with another layer.

I also use BeyondCompare, but haven't tried using it directly with SVN. I use BC to copy changes back and forth between the web directory I use for testing and the directory containing the working copy.

By the way, I've been beta testing BC3, which has a native linux version, and also a three-way merge feature.

Quote:
If anyone has time to read this, could he give us his input here ?

marcan, do you have a more specific question? There's a lot of information in that chapter.

I would like some inputs on what is the very best way to merge branches. I personally am currently using BeyondCompare and I'm manually merging the changes. Is there a better way ?