[sword-devel] sword svn

[DM Smith]

On Apr 13, 2009, at 5:31 PM, Chris Little wrote:

> Jonathan Marsden wrote:
>> Matthew Talbert wrote:
>>> I subscribe to sword-svn as an attempt to educate myself on the
>>> library, and, of course, to keep track of current changes. It  
>>> would be
>>> a real help to me if the commit messages were longer and more
>>> informative. As I am very new to a lot of the engine stuff, it is  
>>> hard
>>> to tell just by looking at the commits what problem they are
>>> attempting to solve.
>> +1
>> I've not (yet?) subscribed to sword-svn, but I have grabbed the svn  
>> tree and looked through svn log to see what has been changing and  
>> why.  Like you, I found the commit messages somewhat cryptic.
>> Ideally, I think bugs and enhancements would appear and be  
>> described in a bug tracker, and then VCS commit msgs can include  
>> something like (Fixes: #12345) so that there is a pointer to more  
>> verbose info on the "why" of any given change.  While I'd love to  
>> see something like that for SWORD, I don't know if that approach is  
>> reasonable/feasible for the SWORD developers, and it is their code,  
>> not mine -- at this point I am very much just a "lurker" when it  
>> comes to that code :)
>
> This scheme would work fine if folks would use the bugtracker (i.e.  
> not report bugs only to sword-devel or in the wiki). When I fix  
> things in the library that I notice myself, I don't tend to file a  
> bug report before fixing them--I just fix them--and I would expect  
> others who work on the library to do likewise. I only open new bugs  
> in the tracker for things that I don't intend to fix myself or that  
> I don't intend to fix soon.
>
> Not filing bug reports in the tracker is generally just a good way  
> to have your bug be ignored because it will quickly be forgotten.  
> The bugtracker provides nice persistence.

I've been lurking on lucene-dev for a while now and I like their model:
1) Discuss a bug or feature on lucene-dev first. This step is somewhat  
optional depending on what the issue is. Obvious bugs often skip this  
discussion.
2) Based on discussion (or lack thereof) open an issue in the bug  
tracker (they use Jira also). Often a link to the thread is put in  
there.
3) For each issue it is assigned a release and generally to a person.
4) All further discussion is done via Jira comments. All activity in  
Jira is redirected to the mailing list.
5) All patches, including new code is communicated via attachments in  
Jira. Patches will sit at least a day before being commited to give  
people time to respond. Seeing, "I'll commit this in a day or two" is  
a common last comment.
6) Robust test cases are provided for new code and modified code. If  
the modification was due to a bug, the existing test cases are  
modified to show it as a failure.

They have  a well-documented backward compatibility requirement. This  
only pertains to the "public" API. They use @deprecated in the comment  
block to indicate what will be removed when backward compatibility is  
removed. Also, they will add comments to a method that is not private  
for mechanical reasons or is otherwise not guaranteed, e.g. "experts  
only" and "experimental" methods.

The robust test cases are the basis of ensuring backward  
compatibility. Lucene uses a 3 part release number (e.g. 2.4.3)  
Essentially backward compatibility may be broken only when the first  
number changes. When the first number does not change, the core  
library can be replaced without any code changes. The third number is  
a bug fix release. The second number is used for two purposes. The x.9  
release is the last release of the series. The only difference between  
1.9 and 2.0 is that deprecations are removed. Typically, an x.0  
release is followed by a x.1 release containing stuff that couldn't be  
put in the prior series.

As an Apache project, they have a formal agreement on who gets to do  
commits and how they get that priv. While all committers are equal,  
some are more equal than others. The founder of the project, who  
provided the original code, has, out of respect, veto capability. But  
otherwise, he is essentially hands-off. People who have commit privs  
also follow this model.

Occasionally, backward compatibility is deliberately broken, and by  
general agreement by committers. Consensus is highly valued for these  
changes. Typically, this is because a bug that might be relied upon is  
fixed. These changes are well publicized.

The "CHANGES.txt" is created from JIRA.

I've started to follow this model for JSword, albeit slowly. I still  
have the habit of making a change directly, because I can, and then  
maybe putting an issue for it in JIRA. We've not used Jira for  
discussion. And we are just starting to use it for patches.

I'm hoping that it will make JSword more of a transparent, community  
effort.

In Him,
	DM