To be clear: branches would be "deprecated" asap, and we would stop maintaining them (committing to them) when all clients are updated. The older branches would be eventually buried in history, and with very explicit naming like 1.0.1, I don't see where confusion could be. Keeping 'master' as the current latest styles for a given CSL version would also be a very nice way to make it idiot-proof to get the latest styles for the most up-to-date clients at any given time.
Also, looking at the history of CSL, you guys have been quite conservative, and I mean this in a good way. So it does not look like we are going to create branches nilly-willy every week. I think we still have a long time before we have a 'plethora' of branches ;-) Finally, I don't have the experience of going from the 0.8.1 to the 1.0 version of the styles. Whatever you guys learnt from it should be taken into account, but I can't speak much on that. It can definitly help to explicitely stating rules for expected changes between minor versions of the CSL, like restricting changes to only adding new attributes or adding new options for given attributes. Now, if you change the default value of an attribute, that does not break a client, but it certainly makes it behave wrongly, yet it could be considered a minor change. There is potentially the issue of adding an attribute or an option that makes it much easier to deal with certain rules, in a way that would have been possible, but painful in 1.0. So you'd want to edit old styles or create new styles with those simplified attributes. These styles will work perfectly with 1.0.1 clients, but will produce a worse output on 1.0 client, even though that could be prevented by using the complicated workaround and still have the same output with 1.0. Maybe these are not actual possibilities, but I am just wondering if even minor changes can still result in 1.0.1 styles being a step back for clients still expecting 1.0. And I am pointing this out because even if those cases, a separate branch would ease the transition. Bruce, in any case, you have not explicitely stated how you see the transition going. Do you mean maybe that at some point X in time, we decide from now on, we can have 1.0.1 styles in the 'master' branch and that's it? That's definitely an option, but I don't know if this is what you have in mind. charles On Jul 24, 2012, at 3:42 PM, Bruce D'Arcus wrote: > Charles: I think you're exactly right. Perhaps this suggests the spec should > say something about this, and we ought to avoid the potential situation of > having a plethora of named branches in a few years, which would be bad for > everyone: developers, users, style maintainers. > > On Jul 24, 2012 3:38 PM, "Charles Parnot" <[email protected]> wrote: > I think a separate branch would be useful. But Bruce, I think the question is > also how to manage the transition. > > In the case of Papers, it will honestly be very easy, as the current CSL > engine will just work and ignore unknown attributes or elements. But for > other clients, having a separate branch is the only way to provide a > transition path, no? > > charles > > > On Jul 24, 2012, at 3:27 PM, Rintze Zelle wrote: > > > Yes we do. > > > > Rintze > > > > On Tue, Jul 24, 2012 at 6:25 PM, Bruce D'Arcus <[email protected]> wrote: > > Not following this closely ATM, but do we really want to have branches for > > every minor release (like 1.01)? I think not. > > > > On Jul 24, 2012 1:24 PM, "Charles Parnot" <[email protected]> wrote: > > I think it is indeed important to have that discussion, because it would be > > nice to start building a 1.0.1 library of styles. > > > > It is also true that the 'master' branch almost looks like it has no role > > other than an alias for the official stable version. But in a way, that is > > exactly what master is supposed to be, so it's not necessarily a bad thing > > to keep it around for that role. > > > > With the Travis CI stuff in place, I think we can have the following setup > > (sorry it's again different from the proposals so far): > > > > * one branch for each version, where only Travis-approved commits go, thus > > for instance: > > - branch "1.0" > > - branch "1.0.1" > > - branch "1.1" > > - branch "master" = same as 1.0 for now, and soon same as 1.0.1, etc... > > > > * ...and one branch for each version, that will be the development branch > > for each, thus for instance: > > - branch "dev-1.0" > > - branch "dev-1.0.1" > > - branch "dev-1.1" > > > > Those latter branches are the ones being tested by Travis, with the Travis > > config files pointing at the different schemas for validation, and the > > extra checks potentially also version-dependent (maybe we enforce more > > things as versions evolve, in addition to the pure XML validation). > > > > As part of the Travis-CI run, validated commits are automatically pushed to > > the non-dev branch for that version. Thus any commit valid in "dev-1.0" > > goes into "1.0", any commit valid in "dev-1.0.1" goes into "1.0.1", etc… > > And for the current stable version, also pushed to "master". So for now, > > any commit valid in "dev-1.0" goes into "master" as well. > > > > The workflows are then very straightforward: > > > > - The bulk of the style tweaks and additions is done on the current stable > > version of CSL, e.g. soon "dev-1.0-1" > > - Work on future versions for styles are done in the corresponding > > branches, e.g. "dev-1.1" > > - Put older versions on maintenance mode, and keep them consistent with > > current version during a transition period > > - Clients can pull from the non-dev branches of their choice, e.g. maybe > > pull from "1.0", or from "1.0.1" if they are ready > > > > > > In this context, assuming for instance that 1.0.1 has become the current > > stable version (soon!), we can do all the following things: > > > > 1. work on the current dev branch "dev-1.0.1", where most of the > > modifications are supposed to take place, including merging pull requests; > > fix errors after the fact when reported by Travis-CI > > > > 2. work on future versions on "dev-1.1", including pull requests; fix > > errors after the fact when reported by Travis-CI > > > > 3. on a regular basis, merge changes from "dev-1.0.1" into "dev-1.1" so > > style tweaks are properly applied to the future styles as well; this > > requires to manually check that we are not overriding elements or > > properties that take advantage of the new version; deprecated stuff, or > > bigger schema changes would also be caught by the Travis validation > > > > 4. on a regular basis, but only during the transition, also merge changes > > from "dev-1.0.1" back into "dev-1.0", so style tweaks are applied to older > > versions; note that this process does not need to be manually checked, > > since any incompatible feature will be flagged by Travis and can then be > > corrected before it gets into the "1.0" branch > > > > 5. pull requests on older styles can be accepted into "dev-1.0", but we > > **never** merge 1.0 into 1.0.1 (the situation is different from point 3 > > above); fix errors after the fact when reported by Travis-CI; such direct > > changes should be the exception, because it's likely that any tweaks to the > > 1.0 style should also apply to 1.0.1 > > > > > > I think it's the best way to take full advantage of the set up with Travis > > CI. IMO, the tricky part is point (3), because it's possible to > > inadvertently remove an element or property taking advantage of a new > > feature. It should be very straightforward for the 1.0 to 1.0.1 transition. > > However, the transition from 1.0.1 to 1.1 might be trickier, as the > > structure of the CSL could have significant changes, enough to break things > > more often. But no matter what we do, it's going to be tricky to maintain > > styles that take advantage of new features, and at the same time merging > > the everyday changes we make to those styles. The merging strategy may or > > may not be the best way to achieve that, but having a separate branch will > > always help. > > > > Those were my 2 cents :-) > > > > charles > > > > > > On Jul 24, 2012, at 10:03 AM, Rintze Zelle wrote: > > > > > On Tue, Jul 24, 2012 at 12:49 PM, Simon Kornblith <[email protected]> > > > wrote: > > > On Jul 24, 2012, at 12:27 PM, Rintze Zelle <[email protected]> wrote: > > > > > >> On Thu, Jul 19, 2012 at 5:40 PM, Sylvester Keil <[email protected]> > > >> wrote: > > >> Another question we should keep in mind whether it may not be easier to > > >> work on the master branch and have separate release branches? Especially > > >> if we may want to keep separate versions of styles in the future (i.e., > > >> 1.0 branch, 1.0.1 branch). > > >> > > >> I think nobody objects against having separate branches for the > > >> different CSL releases. The minimal branch structure would then be: > > >> "0.8.1", "1.0", "1.0.1" (and so on), "master". > > >> > > >> To enable people to subscribe to a CSL branch without having to worry > > >> that this cloned branch changes version (which would happen in "master" > > >> with our current setup ), we would need a branch for the current CSL > > >> release, in addition to branches for older CSL releases. > > >> > > >> That arrangement by itself however doesn't solve the problem of > > >> preventing invalid styles from ending up in the version branches, and > > >> we'll likely want to be able to accept patches for older CSL versions. I > > >> can think of two options here: > > >> > > >> a) we keep using "master" for accepting CSL styles of the most recent > > >> CSL version, and allow direct commits and merging of pull requests with > > >> invalid CSL styles. We also accept pull requests to version branches of > > >> older CSL releases, but only once Travis CI has checked them. A GitHub > > >> service hook can be used to check the "master" branch after each commit, > > >> and push the commit to the most recent CSL version branch if there are > > >> no errors (the service hook script can either wait for Travis CI or run > > >> the tests itself). > > >> > > >> b) we keep using "master" for accepting CSL styles of the most recent > > >> CSL version, but only accept pull requests. We also accept pull requests > > >> to version branches of older CSL releases. In both cases, we would only > > >> merge pull requests once Travis CI has checked them. A GitHub service > > >> hook can be used to automatically push any changes made to "master" to > > >> the most recent CSL version branch. > > >> > > >> The downside of only relying on pull requests is that fixing small > > >> errors can be cumbersome (you have to download the file(s) by hand via > > >> the GitHub web interface), because the CSL team members typically won't > > >> have commit access to the fork of the person making the pull request. In > > >> some cases it might be easier to accept broken styles and fix them up > > >> after merging. > > > > > > I like the second approach, but in that case, I'm not sure a master > > > branch is necessary at all. GitHub allows you to rename the master branch > > > and set a different default branch for a repository. The master branch > > > could also be a symbolic-ref to the most recent version branch. > > > > > > You can fix small errors before pushing to the repository if you merge > > > pull requests the command line way: > > > > > > git fetch git://github.com/<<USER>>/styles.git > > > git merge <<COMMIT HASH>>> > > > # Fix and commit fixes > > > git push > > > > > > Good to know, and I agree that mirroring "master" against the most recent > > > CSL release is unnecessary. However, we might want one additional branch > > > (which can be either "master", "development", or "experimental") to > > > accept styles that validate against the schema trunk. It might be handy > > > to have some styles available for testing before an official CSL release > > > (the current policy is to reject CSL 1.0.1 styles, since everything in > > > the "master" branch should validate against the CSL 1.0 schema). > > > > > > Rintze > > > ------------------------------------------------------------------------------ > > > Live Security Virtual Conference > > > Exclusive live event will cover all the ways today's security and > > > threat landscape has changed and how IT managers can respond. Discussions > > > will include endpoint security, mobile security and the latest in malware > > > threats. > > > http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/_______________________________________________ > > > xbiblio-devel mailing list > > > [email protected] > > > https://lists.sourceforge.net/lists/listinfo/xbiblio-devel > > > > -- > > Charles Parnot > > [email protected] > > twitter: @cparnot > > http://mekentosj.com > > > > > > > > ------------------------------------------------------------------------------ > > Live Security Virtual Conference > > Exclusive live event will cover all the ways today's security and > > threat landscape has changed and how IT managers can respond. Discussions > > will include endpoint security, mobile security and the latest in malware > > threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/ > > _______________________________________________ > > xbiblio-devel mailing list > > [email protected] > > https://lists.sourceforge.net/lists/listinfo/xbiblio-devel > > > > ------------------------------------------------------------------------------ > > Live Security Virtual Conference > > Exclusive live event will cover all the ways today's security and > > threat landscape has changed and how IT managers can respond. Discussions > > will include endpoint security, mobile security and the latest in malware > > threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/ > > _______________________________________________ > > xbiblio-devel mailing list > > [email protected] > > https://lists.sourceforge.net/lists/listinfo/xbiblio-devel > > > > > > ------------------------------------------------------------------------------ > > Live Security Virtual Conference > > Exclusive live event will cover all the ways today's security and > > threat landscape has changed and how IT managers can respond. Discussions > > will include endpoint security, mobile security and the latest in malware > > threats. > > http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/_______________________________________________ > > xbiblio-devel mailing list > > [email protected] > > https://lists.sourceforge.net/lists/listinfo/xbiblio-devel > > -- > Charles Parnot > [email protected] > twitter: @cparnot > http://mekentosj.com > > > > ------------------------------------------------------------------------------ > Live Security Virtual Conference > Exclusive live event will cover all the ways today's security and > threat landscape has changed and how IT managers can respond. Discussions > will include endpoint security, mobile security and the latest in malware > threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/ > _______________________________________________ > xbiblio-devel mailing list > [email protected] > https://lists.sourceforge.net/lists/listinfo/xbiblio-devel > ------------------------------------------------------------------------------ > Live Security Virtual Conference > Exclusive live event will cover all the ways today's security and > threat landscape has changed and how IT managers can respond. Discussions > will include endpoint security, mobile security and the latest in malware > threats. > http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/_______________________________________________ > xbiblio-devel mailing list > [email protected] > https://lists.sourceforge.net/lists/listinfo/xbiblio-devel -- Charles Parnot [email protected] twitter: @cparnot http://mekentosj.com ------------------------------------------------------------------------------ Live Security Virtual Conference Exclusive live event will cover all the ways today's security and threat landscape has changed and how IT managers can respond. Discussions will include endpoint security, mobile security and the latest in malware threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/ _______________________________________________ xbiblio-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/xbiblio-devel
