library
library copied to clipboard
VCVRack
SUGGESTION: Standardized Git Labels/Branch usage
I am not a module developer, but I am a software developer with nearly a decade's experience with git, so I feel qualified to comment.
I really appreciate the amazingly dynamic and rapid development on VCV rack. But as you all know, it can be a little chaotic.
One of the issue I run into is this: How do I get the latest, best version of each module's source?
This isn't a straightforward question. Many of the module developers are new to Git, and there are obvious ways they've made mistakes, including (but not limited to):
- master (i.e. main central development branch) won't compile.
- object files (.o .obj etc) checked into git.
- files with conflict markers checked in (i.e. a failed merge leaving <<<<<<<, ========, >>>>>>>> lines in source.
It would be immensely helpful if there was a standardized method to get the last good version to compile.
What would that entail?
- do new development on a branch, and keep releases on the master branch
- tag releases with consistent tag names.
Right now my build script looks at the tags in each repo and checks out the last tag. This seems to be a good compromise for the purposes of getting a known-good compile. The community repo script (community-builds-from-source.sh) just assumes the master branch is the best.
Neither of these approaches is ideal. Some repositories (as I mentioned) are broken at the head revision of the master branch, and some use tags inconsistently.
I don't know what the proper solution is, and I'm assuming Andrew Belt has an opinion about it that would carry more weight than mine. My suggestion would be:
- Do all development on a branch, and merge to master when it's verified working.
- tag releases consistently: I don't care what system is used, but my preference would be
. . where . match the main Rack API version, e.g. 5.1
Let this be the beginning of a discussion. Rack is becoming too large a thing to just leave things to a 'wild west,' anything goes environment. What will end up happening is the main developers (i.e. Andrew et al) spending too much time trying to corral module developers, and end users not knowing what they're getting.
I think the recommended method should be the one you first described:
- master branch holds latest code
- tag for each version
- branch only if there is an improvement on a previous tag (e.g. have commits after tag v0.5.17 and want to make a v0.5.18 release which is compatible with Rack v0.5)
As you demonstrated yourself, many people don't know git, so using branches overcomplicates things. If you want to write a script to automatically check out the latest tag, that would always work if everyone followed this straightforward method (which seems to be the case).
Your suggestion seems to suggest you have not read https://github.com/VCVRack/Rack/issues/266, which implies that all v0.5.* plugins are compatible with Rack v0.5.*.
No, #266 is roughly #255 in the Rack issues I haven't read. What you're saying is that you've already considered this problem and come up with a valid solution. I was coming at it from the other direction: Observing the current situation of the modules available as source code.
The only thing I don't get is "branch only if there is an improvement on the latest release"
Since git branches are arbitrary -- I've even fixed messed up repos by deleting 'master' and recreating it on a more reasonable SHA -- what 'master' is, is only a convention.
My experience in development is that releases are tagged SHAs on the master branches. New features are implemented on a branch, and then merged back into master when they're complete. Actual releases are tags on specific SHAs on the master branch.
Your method seems to be the opposite: 0.5 is the release branch and occasionally you backport changes to it from master, but master is a work in progress. Horses for courses, as they say.
In my third bullet, I was only saying that branches are unnecessary unless you need to branch from the latest tagged release which is N commits behind HEAD. I wasn't restricting the use of branches. By all means, branch as much as you want in your plugins.
Rack does the same. Tag v0.5.0 was improved with tag v0.5.1, but ABI-breaking improvements were already on the master branch, so I branched from v0.5.0 using a new v0.5 branch. Hopefully this clears it up.
Just wanted to drop a thought on this here..
Leaving aside for a moment the concerns of a plugin-building script, the majority use case to be considered, numerically, is likely not that of a plugin developer, but that of an enthusiastic but non-developer Rack user who wants to download and build the latest and greatest.
From that point of view, I think it's worth recommending plugin authors create branches equivalent to the Rack versions those branches build against, and leave tags for releases. The logic being simply that branches are very visible in the github web ui, and very easily seen and switched to in git itself.
As developers of long acquaintance with git, it's easy to lose sight of the obscurity of tags (relative to branches) for beginners and non-developers. Adopting this sort of branch-per-version pattern seems to have the best chance of reducing friction for the adventurous types who jump into building from source, IMO.
@ndrspcfd Already recommended here. https://github.com/VCVRack/Rack/issues/258#issuecomment-374835308 If it's a requirement, it becomes more problematic when developers don't follow it than if it's a suggestion. Branches don't just correspond to versions but also experimental features. Tags are only for signaling "this is what the official release was built from". There is no reason to build a tag for your own use instead of just the latest commit on a branch.
@AndrewBelt Right! - Good thinking there :) And yeah, it would be crazy to try and insist on any of that, but sensible recommendations are a Good Thing.