Start tagging/versioning updates

[derekstavis]

We need a way to versionate repository changes via git tags and ensure that omf update only fetch and upgrade using tags too. This way we can continue developing on master branch without breaking user installations. It will also make easier to report bugs and track them too.

[oranja]

If I may, I like the idea of tagging releases. :)
Is there any way I can help?

p.s.
As an intermediate stage, it's also possible to do all development and testing on a dev branch and only push to master when it's stable.

[bpinto]

Hey, that would be great!

We were thinking about having a stable release before we start using tagged releases but I'd like to hear what you have to say about this. Maybe we are wrong :)

[oranja]

Naturally any version tag should point to a stable release.
On the upside, I wouldn't say that OMF is not stable, judging by the fact that everything seems to work fine right out of the box. I do, however, think that introducing named releases should be a planned move (and I'm not a huge fan of plans, if it means anything).

My humble suggestions are as follows:

1. First things first - separate dev from master.
   Fish newcomers are probably also OMF newcomers, and vice versa. If things get rough too soon, most of them will take a u-turn and never come back to either of them (see: vim). Fish is all about love on first sight. So perhaps now things are fine, but as long as anyone who uses OMF gets it straight from the master branch, it will become an impediment. Putting end-users and collaborators on the same branch means that end-users will have to put up with breakages and devs will have to tip toe.
   Do development in topic branches, bug-fixes in dev, test from dev, push the ripe fruit to master, or something like that (see: git-flow). This is also not mutually exclusive with version tags, so why not do both anyway?
2. If you want to be taken seriously, I guess you should take yourself seriously. Not too seriously, obviously, but seriously enough to set a milestone and a few modest goals. Looking at the current issues and the way things are, I think OMF can and should strive to hit a milestone and have a proud first release tag.
   1. Plugins. pkg? plugin? omf-? Let's sort this out once and for all.
      Now, to add to the confusion, let's take the gitignore (gi) plugin for example. There is a oh-my-fish/ repository and a wa/ repository for it. One seems very old, one seems newer. OMF's db points to the newer wa/ repository, but it has a very overt bug (try gi update) and it's less well-organized (all functions in a single file). Why do these duplicates exist? It also comes with a consequence. I wanted to open an issue (and a PR), but couldn't decide where it should be. This perceived neglect is demotivating.
   2. Support an optional omf- prefix for repos? #152 and System package dependencies #196 lead to the same conclusion: Conventions are great, but packages can't rely on conventions alone anymore. It's cumbersome and not flexible enough. Besides, it makes the code more patch-y. Metadata should be a part of every package. Name, type, and dependencies. At some point there might be a need to add a version field. Descriptions can be optional. It shouldn't be too hard to implement and through this process we also get to do some house cleaning and make sure all plugins are up to date.
   3. I saw @bpinto's recent PR with some basic tests. I think that this is a great step forward to declare a certain build stable. Personally I would like it if there was some virtual OS X environment for testing. As a collaborator I want to make sure I don't make a fool of myself and other users. The same goes for a Linux environment, of course, but that's a piece of cake. You already have docker and it's easy to get a shell.

[sagebind]

Thanks for the suggestions! Let me see if I can comment on some of them.

1. I really like this idea a lot. We should do this, basically immediately, since the current version is the version everyone uses anyway and is as "stable" as we have right now.
2. 1. We should be careful not to make things too complex though. After all, this is a shell customization framework, not a programming language dependency manager.
   2. Yay! I love tests. :)
   3. Well, some of the disorganization came recently from some... interesting project merging and restructuring and splitting and... stuff. Regardless, I do agree that we should do a little house cleaning.

[bpinto]

Awesome!

My idea is to start writing some issues and later assign some of them to a milestone. I'd however only assign an issue to a milestone if someone is going to do it.

Regarding tests, I have started working on this other framework and its still very basic but it is the best tool I have seen so far for testing fish scripts. The other frameworks I have seen are super complicated and hard to write/read tests.

I'm willing to add tests for the crucial parts of the system as we have almost no tests at the moment. And from now on, focus on releasing features covered by tests only.

[bpinto]

Do development in topic branches, bug-fixes in dev, test from dev, push the ripe fruit to master, or something like that (see: git-flow). This is also not mutually exclusive with version tags, so why not do both anyway?

I am not a fan of git-flow. I would rather avoid it and keep it simple:

1. Master is the branch where new features are added to.
2. Use feature branches for developing features.
3. Use branches for major and minor versions.
4. Use tags for patch versions.
5. Default installation to a release (tagged commit).

[bpinto]

I saw @bpinto's recent PR with some basic tests. I think that this is a great step forward to declare a certain build stable. Personally I would like it if there was some virtual OS X environment for testing. As a collaborator I want to make sure I don't make a fool of myself and other users. The same goes for a Linux environment, of course, but that's a piece of cake. You already have docker and it's easy to get a shell.

Travis does support running builds on OSX, but we wouldn't be able to use docker for that. 💭

I'm unsure now... perhaps we should lose the benefits of doing the tests on a clean environment with docker so that we can run tests on OS X and linux.

[bpinto]

Plugins. pkg? plugin? omf-? Let's sort this out once and for all. Now, to add to the confusion, let's take the gitignore (gi) plugin for example. There is a oh-my-fish/ repository and a wa/ repository for it. One seems very old, one seems newer. OMF's db points to the newer wa/ repository, but it has a very overt bug (try gi update) and it's less well-organized (all functions in a single file). Why do these duplicates exist? It also comes with a consequence. I wanted to open an issue (and a PR), but couldn't decide where it should be. This perceived neglect is demotivating.

All db should point to omf instead of wa now. As omf plugins have a different layout than wa.

[derekstavis]

First things first - separate dev from master.

(...) Putting end-users and collaborators on the same branch means that end-users will have to put up with breakages and devs will have to tip toe.

I see your point in it, but I do prefer following tagged releases in installer and updater, and keep master as "unstable" (where unstable means stable but not 100% sure of stability). I agree with what @bpinto proposes:

1. Master is the branch where new features are added to master (unstable).
2. Use feature branches for developing features.
3. Use branches for major and minor versions.
4. Use tags for patch versions.
5. Default installation to a release (tagged commit)

Plugins. pkg? plugin? omf-? Let's sort this out once and for all.

Yeah, this is something we inherited from a merge and we need to sort out. The thing to solve this issue (and others too) is a metadata file. See discussion in #196.

There is a oh-my-fish/ repository and a wa/ repository for it.

This perceived neglect is demotivating.

Oh My Fish still suffers from a violent merge we had in the past. Surely we need to get away from Wahoo packages by creating our own maintained packages, as this way we can evolve faster by having our own package maintainers. If you think you can port a wa/ namespaced package to oh-my-fish/ namespace we can allocate a repository for you.

Metadata should be a part of every package. Name, type, and dependencies. At some point there might be a need to add a version field. Descriptions can be optional.

I agree with you, and this have been on my plans for months with the exact same data. We implemented package dependencies in #149, the next step is to add the metadata, again, see #196.

It shouldn't be too hard to implement and through this process we also get to do some house cleaning and make sure all plugins are up to date.

Help is very appreciated in this. We need maintainers, we also need better documentation. You are very welcome to help us with if you want.

[sagebind]

I've looked back at this issue and I now think that this should be high-priority, especially with the new changes planned. Features can't be merged quickly because it might damage user installations, and this is stalling development speed.

Since this is a fairly simple project that moves forward generally, I don't expect backported patches to old versions, so I propose a simpler variant proposed by @derekstavis and @bpinto:

1. Master is the branch where new features are added to master (unstable).
2. Use feature branches for developing features.
3. Use tags for major, minor, and patch versions.
4. Default installation to a release (tagged commit)

I am willing to implement this in the installer and in the updater immediately if I can get approval.

[bpinto]

I totally agree!
On Wed, 30 Mar 2016 at 15:47 Stephen M. Coakley notifications@github.com
wrote:

I've looked back at this issue and I now think that this should be
high-priority, especially with the new changes planned. Features can't be
merged quickly because it might damage user installations, and this is
stalling development speed.

Since this is a fairly simple project that moves forward generally, I
don't expect backported patches to old versions, so I propose a simpler
variant proposed by @derekstavis https://github.com/derekstavis and
@bpinto https://github.com/bpinto:

1. Master is the branch where new features are added to master
   (unstable).
2. Use feature branches for developing features.
3. Use tags for major, minor, and patch versions.
4. Default installation to a release (tagged commit)

I am willing to implement this in the installer and in the updater
immediately if I can get approval.

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#10 (comment)

[oranja]

The dev branch never happened, so yeah, let's keep master as the bleeding-edge branch and tag releases as we go.
And we can keep directing all PRs to master, exactly as we did so so far. I have yet to see a feature developed on a branch by more than a single contributor.

[sagebind]

I propose the following version scheme:

• Major version: Indicates backwards-incompatible API changes. Also used when the project improvements seem significant enough for a new major version. Core contributors can feel this out as needed.
• Minor version: Indicates user-facing changes that change how user commands might be used, and new features released.
• Patch version: Bug fixes and minor improvements.

In addition, I propose following the below guidelines:

• Tagging a new major or minor version requires a consensus from the core team after testing the master branch, whether manually or automated (if more automated tests are added in the future). Releasing a patch version requires only one core contributor to verify that a bugfix works properly before release.
• If a more complex development workflow is required in the future, the system is open to change by core contributors.
• All releases must be accompanied by an addition in a CHANGELOG.md file in the project root. This file may possibly be used by OMF to show changelogs before updating, but is primary for users and contributors to quickly get up to speed on what has changed.

[sheldon]

Hey Everyone

For version numbers, can I humbly suggest [http://semver.org/](Semantec Versioning). I've seen it used well in the past, and it's pretty close to what @CoderStephen is suggesting.

Only 1 potential area I'd change: for Minor versions you can add syntax, but not modify existing syntax. e.g. you would be ok to add a new --new-flag to an existing command, but the previous --old-flags would always need to behave as they did before without the new --new-flag. If the --new-flag caused new behaviour when omitted it should really be a new Major version.

What do you think?

Cheers
Sheldon

[sheldon]

P.S. Once you settle on a scheme, having this kind of info in a doc/wiki or somehting like that would be awesome 🐫

[sagebind]

We've settled on a scheme, and we've now finally merged in support for updating to specific tags via PR #293, so marking this issue as closed.