Brother Samuel asked, so here goes... First of all, let me make it clear that it is not my intention to offend anyone or start a flame war with this message. This is STRICTLY MY OPINION and I realize there are plenty of valid ways of doing things. I am not saying the way we are currently doing things is wrong. It is just my hope that we can kick off a discussion as a way of improving.
I also apologize in advance for the length if this message. These are my thoughts on software development specifically as applied to Gregorio. *** User Focus *** If there are people besides yourself who are going to use the software you write, you need to be cognizant of their needs. As a user myself, these are the deficiencies I have noticed. Version Numbers I believe that at some point, the intent was to have Gregorio follow semantic versioning. From http://semver.org/, this means 1. MAJOR version when you make incompatible API changes, 2. MINOR version when you add functionality in a backwards-compatible manner, and 3. PATCH version when you make backwards-compatible bug fixes. I think this is a very good idea. It would let users know how much of a change they have coming when upgrading. As I have mentioned in an earlier email, it makes it easy to decide if you are willing to "risk" an upgrade given your current situation. *** Backwards Compatibility *** I realize that change is necessary, and incompatible change is inevitable, especially if you want to keep things clean and manageable. This is what semantic major releases are for. However, I think that the backwards-compatible option should always be the first option explored when making changes. For example, the changes to \includescore introduce new functionality that is used by default. To get the old functionality, one needs to modify their previously working code. This could have been done in a backwards-compatible way. Two ways come quickly to mind: 1. Refactor things so that \includescore continues to work the same way and introduce a new command (i.e., \includegabc) that works the new way or have the optional argument turn on the functionality rather than turning it off. 2. Have the code take the argument to \includescore and use that to decide which way to go. If there is no extension or a .gabc extension, then do things the new way. If there is a .tex extension, do things the old way. This feature is new, so if you want it, you can easily use it for future projects instead of it breaking old projects by default. By doing this in a backwards-compatible manner, at the very least, it means one less thing to do when upgrading projects, and there's even a chance that nothing needs to be done for things to continue to work. Practically speaking, had this been backward compatible, issue #83 would not have occurred. In this case, it also would have been one less thing for the Gregorio maintainers to maintain. A good example of a place where backwards compatibility should be abandoned is the space refactoring. The behavior before was inconsistent, so, in my opinion, consistency outweighs backwards compatibility. However these kinds of changes must be clearly documented, which leads to... *** Documentation for Upgrades *** As I've said before, I think Gregorio should have an upgrade "cheat sheet" for major versions. Something that a user can quickly look at when the time comes to upgrade a project to the new version. It should basically we a point-by-point list of things that a user needs to do when upgrading from one major version to the next (i.e., whenever the API changes). When you're under time pressure, the last thing you want to do is to have to read through all the change logs, mailing list messages, and source code to figure out how to get your project working again. *** Beta Branch *** Especially incrementing the major version, but perhaps when incrementing the minor one as well, some users can tolerate being on the bleeding edge whereas some users would like stability. This can be handled with good tagging, release, and snapshot builds, etc., but (being a Linux user where the only option is really to install the git version) I propose the beta branch approach. Google uses this approach with their Chrome browser. In fact, there are three branches there: stable, beta, and experimental (for those who really want to bleed). When developing new, especially incompatible, changes, do this in a beta branch (either a named non-master branch in the current repository or another clone of the repository). Make all the changes in the branch, and after it's had time to stabilize, merge it into the master branch. Those who want the bleeding edge can build from the beta branch. Those who don't can stick with the master branch. As of right now, the master branch of the main repository has been broken for a few days running against a major project that I'm working on. I am willing to be on the bleeding edge, so that's fine, but if I weren't, it would be nice if the default branch (master) of the git repository was stable and working. *** Unit Tests *** I think there should be a repository of test scores that need to pass (or be made to pass) before unleashing a new version of the Gregorio on the unsuspecting public. In the past few days, I've come up with a number of minimum working examples (based on my large project) that I've used to report issues. It would be nice to place these into a subdirectory of the Gregorio repository with a way to run them against the currently checked-out version of the software, or if that is not desired, in a different repository. As issues arise, more test cases can be added as a way of ensuring and improving the quality of each release. I can try to set this up, if you would like me to. ... And that's it. What do you think? Anything here worth adopting at some level? Regards, Henry _______________________________________________ Gregorio-users mailing list [email protected] https://mail.gna.org/listinfo/gregorio-users
