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 thelibrary, and, of course, to keep track of current changes. It would bea real help to me if the commit messages were longer and moreinformative. As I am very new to a lot of the engine stuff, it is hardto tell just by looking at the commits what problem they are attempting to solve.+1I'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
_______________________________________________
sword-devel mailing list: sword-devel@crosswire.org
http://www.crosswire.org/mailman/listinfo/sword-devel
Instructions to unsubscribe/change your settings at above page
