Tiddlywiki5: Adopt branch-based development for v5.1.20

[Jermolene]

UPDATE: 15th January 2019

We've now implemented the following scheme:

• The branch master is the latest prerelease and is deployed to https://tiddlywiki.com/prerelease
• The branch tiddlywiki-com is for documentation updates; the editions in this branch are deployed with the latest release version of the core

Thus, documentation update PRs should target tiddlywiki-com and functionality updates should target master. The core team will periodically merge the tiddlywiki-com changes into master.

---

It is proposed to create a new v5.1.19 branch for changes for v5.1.19, while keeping the master branch for the current v5.1.18 release so that we can rapidly accept and publish documentation changes and updates for v5.1.18 prior to the release of v5.1.19.

The background is that as discussed in #3115, we'd like to introduce continuous integration for the TiddlyWiki 5 project. One of the benefits will be the ability to easily and immediately update tiddlywiki.com with documentation changes -- as soon as a documentation change is pushed to the master branch, tiddlywiki.com will be automatically rebuilt, and in a few minutes will reflect the change.

However, our current development strategy of pushing all changes to the master branch has meant that it is not possible to update tiddlywiki.com with the latest documentation changes without also including the documentation updates made for new features. Continuous integration doesn't solve this problem.

The new v5.1.19 branch will allow us to keep the v5.1.19 changes separate, and keep making changes to master to update tiddlywiki.com.

Some notes/questions on the consequences of this proposal:

• We'll have to keep updating the v5.1.19 branch with the latest changes from master
• I think this arrangement is going to be more burdensome on all contributors (because they're going to have to figure out the correct branch for their PR), and for the core team (because there'll be a lot of merge conflicts)
• Rather than using the version number for the branch containing the upcoming release, perhaps we should just use a branch name like "prerelease"?

What do others think? Any relevant experiences with other projects?

[diego898]

Hey @Jermolene, for dealing with branches the best resource I've found is:

https://learngitbranching.js.org/

Perhaps this would be of use for developers getting used to the branch strategy.

As far as keeping prerelease (I've seen this typically called "develop" branch) updated - I don't suspect too many merge conflicts as updates to master would be for documentation and other non-core altering changes.

There are several tutorials on master/develop branching strategies and even simpler "git-flow" type strategies. I think once its "frozen", that particular commit can be tagged with the appropriate version number and merged into master. This way, the repo will contain tags for every release and github can be used to manage releases (which is based on tags):

https://help.github.com/articles/creating-releases/

I'd be happy to help further test/setup/explore these strategies (in a dummy repo), and help in any other way I can.

[pmario]

I think it's OK, to name the development branch prerelease. Everyone is used to it.

[diego898]

Hey @Jermolene what do you think? Should we set up some kind of simple tests/documentation?

[inmysocks]

Having all of my work on a development branch which gets merged into master for stable releases has helped a lot with my non tiddlywiki work. I think that having a master branch and a prerelease branch is a good idea.

On my personal server I use git hooks to automatically merge changes to master into the development branches but I don't think that GitHub supports hooks like that. Using the web hooks and a remote server for this seems like it would be inviting race conditions and other headaches that make it lose synchronisation with the github servers, but it may be an option.

I know almost nothing about how the continuous integration works on GitHub, perhaps we could use that to merge master into the prerelease branch when there is an update? If that is possible it could relieve some of the administrative burden.

[Jermolene]

I wonder if it would be less disruptive to our existing practices to create a new branch for the tiddlywiki.com build, called perhaps "tiddlywiki-com". We'd adjust the non-prerelease build scripts to pull content from that branch and build it using the latest released version of the core. The prerelease build scripts would be unchanged.

Most development would proceed on master as we do now while documentation updates would be performed on tiddlywiki-com. As @inmysocks suggests, there may be scope to automate the merging of docs changes into master as well, otherwise we'd have to do it manually. We may also want to use CI to check that nothing is committed to tiddlywiki-com outside of the editions directory.

The choice of what constitutes the master branch comes down to what we want visitors to github.com to see (most will never click the "branches" dropdown). I think backwards compatibility with existing documentation demands that we stick to master being the hairiest and scariest prerelease.

[diego898]

One benefit of adopting branch based development is that bug fixes can still be placed on master, while new features are being developed in the prerelease. For example, recently the new katex plugin has a problem with fonts which is a bug - in principle this can be quickly placed on master (hotfix/quickfix) resulting in a slight a version number bump.

This brings up another question - what is the versioning standard used by TW? It feels like all of the features in 5.1.18 should have resulted in 5.2, while hot/quick/bug fixes result in 5.1.19,5.1.20, etc).

[morosanuae]

This brings up another question - what is the versioning standard used by TW? It feels like all of the features in 5.1.18 should have resulted in 5.2, while hot/quick/bug fixes result in 5.1.19,5.1.20, etc).

@diego898 Please see this old issue: tiddlywiki not following semantic versioning usage (#2279)

[diego898]

thanks @morosanuae - I wonder if now is a time revisit that as were moving to a branch-based development pattern.

If master will only ever contain documentation changes on tw.com, which never get a version number, and prerelease contains both bugfixes and new features, then we could remain with what we have. I think its a missed oppourtunity, however.

[Jermolene]

I still think that "true" semantic versioning doesn't make much sense for TW5 because pure bug fix releases are a rare exception for us.

[Jermolene]

As noted in #3642 this work will now be deferred until v5.1.20, with v5.1.19 being a bug fix release.

[Jermolene]

By the way, much of the work to implement this ticket is over in https://github.com/Jermolene/build.jermolene.github.io/issues/4

[tfeb]

This is only slightly related, but something that would also be good (for me anyway) would be to change to a more semantic versioning convention for TW. At the moment, for instance you just have to know that 5.1.18 was a feature release and 5.1.19 is a bugfix release. More conventionally would be to have (say) 5.2 be a feature release and 5.2.1 be a bugfix release.

I appreciate there may be strong reasons why TW versions should be what they are (ie '5.2 is the release which adds support for unicorns' or something like that).

[Jermolene]

Hi @tfeb I'm open to consider this, but my thoughts at the moment haven't strayed much from my comment in #2279: that we virtually never have pure bug fix releases. Even in the case of v5.1.19 there's actually a new feature, introduced to fix one of the bugs.

[tfeb]

@Jermolene I think that's right: if you never do bug fix releases then mucking around with the version numbering is not worth it. One thing to ask would be 'what would it take to become 5.2.x? or 6.x?'.

I really appreciate the organised releases of TW by the way.

[Jermolene]

Thanks @tfeb!

One thing to ask would be 'what would it take to become 5.2.x? or 6.x?'.

5.2.x would be for a release that breaks backwards compatibility in a minor way (eg. removes a bunch of deprecated features and makes them available in a plugin). 6.x (or 10.x) would be for a release that breaks backwards compatibility in a substantial way (e.g. the structure of a tiddler is changed from a dictionary of name/value pairs to an array of name/value pairs).

[tfeb]

@Jermolene I think that answers my question: version numbers make sense as they are.

PS I think it should be 11.x (5 = 2*2+1) or 26.x (5 = 2^2 + 1).

[00SS]

@Jermolene

Ref:

Most development would proceed on master as we do now while documentation updates would be performed on tiddlywiki-com.

Is this already implemented? Should my documentation pull requests for updating already existing features be made on the tiddlywiki-com branch editions directory instead of the master branch?

[Jermolene]

Apologies for the late reply @00SS. I've added an update to the OP summarising the changes, let me know if anything is unclear.