Mithril.js: Fix Mithril's ad-hoc, confusing release process

[isiahmeadows]

Given increasing numbers of duplicate, already-fixed issues in docs and elsewhere, I feel it'd be helpful if we started better structuring and documenting our release process, as opposed to the ad-hoc mess that goes on now.

@lhorie @tivac I've assigned you two because you're the ones who can actually control releases.

[isiahmeadows]

It might also be a good idea to have the site auto-updated from changes to docs within master, so we can cherry-pick relevant commits from next as applicable without doing a manual rebuild each time.

[gyandeeps]

Coming from consumer front, we use mithril in production. We would really appreciate if their was some rough outline/plan on release schedule. It would really help us and others.

Its better to do smaller releases vs doing a release with ~150 commits. As of right now, there were some important bugs fixed after 1.0.1 but its been a long time and there has been no release.

Any help on this front would be highly appreciated. Thanks

[tivac]

It might also be a good idea to have the site auto-updated from changes to docs within master, so we can cherry-pick relevant commits from next as applicable without doing a manual rebuild each time.

That's what #1689 is for, though it'll require @lhorie to make some changes to the hosting for http://mithril.js.org before it'll take effect.

I'm all for this, here's my preferred flow.

1. Ensure next is passing tests
2. Integrate next to master
3. Ensure master is passing tests
4. npm version <major|minor|patch. -m "v%s" (to ensure the auto-generated tag looks nice)
5. preversion lifecycle script builds bundle & runs tests
6. version lifecycle script kicks in using @studio/changes or something similar to mostly auto-generate changelist
7. postversion lifecycle script pushes changes to github
8. Travis runs build, doesn't commit bundles (since the bundle was generated locally & hasn't changed)
9. gh-pages branch updated with latest docs changes
10. A github release is automatically created with... something. Needs more investigation!

Right now there's a few things that need decisions before that flow can work.

1. [x] any docs push to master will update the site. That's convenient for doc fixes, bad for new features. We'll need to determine if we care and potentially limit pushing docs to just tagged commits.
2. [x] there's no changelist auto-updating in place. I've got a flow I like for personal projects that I'd be happy to apply to mithril, but will need sign-off from at least one other maintainer and preferably Leo.
3. [x] We need to agree on the threshold for a release. IMO we should shoot for at least one patch-level release a month assuming that some changes have landed.
4. [x] We need to decide on whether or not we're strictly following semver or not. Mithril has not in the past, and considering the effort involved in getting the 1.0 release out the door we may want to keep it semver-ish for now.

[isiahmeadows]

@tivac

any docs push to master will update the site. That's convenient for doc fixes, bad for new features. We'll need to determine if we care and potentially limit pushing docs to just tagged commits.

As long as gh-pages is only rebuilt on docs changes, I think it may be manageable. Keep in mind I was intentionally referring to master, not next.

there's no changelist auto-updating in place. I've got a flow I like for personal projects that I'd be happy to apply to mithril, but will need sign-off from at least one other maintainer and preferably Leo.

I'm curious of how this particular workflow works. I usually curate changelogs on my personal projects, and just use the Git history to help me build it, but that wouldn't work here.

We need to agree on the threshold for a release. IMO we should shoot for at least one patch-level release a month assuming that some changes have landed.

👍 from me.

We need to decide on whether or not we're strictly following semver or not. Mithril has not in the past, and considering the effort involved in getting the 1.0 release out the door we may want to keep it semver-ish for now.

I'm okay with semver-ish, and most projects that adopt strict semver early wind up versioning very quickly in a hurry. Given how new the 1.x API is, I don't like the idea of going strict semver yet. Maybe after it naturally stabilizes.

[tivac]

@isiahmeadows

Sounds like we're in agreement on preferred release cadence and versioning in a semver-ish way, so gonna check those off.

I'm curious of how this particular workflow works. I usually curate changelogs on my personal projects, and just use the Git history to help me build it, but that wouldn't work here.

See step 6 in my release workflow. @studio/changes does the heavy-lifting of grabbing git commits into a file. I know the mithril changelog is a bit more complex then that but I think it's nice to automate at least the collection aspect.

[tivac]

As long as gh-pages is only rebuilt on docs changes, I think it may be manageable. Keep in mind I was intentionally referring to master, not next.

I thought about my initial concerns more and they should be fine assuming that we continue only merging to master once things are released. Not sure exactly what I was concerned about previously ¯\_(ツ)_/¯

[pygy]

:+1: in general... Just currious, does @studio/changes pause the npm release script while you edit the change log?

[tivac]

@pygy yeah. It uses editor's callback to launch your editor and wait until you're done editing the file before continuing on.

[isiahmeadows]

@tivac Interesting project (I missed the link on first read). I probably wouldn't use that for my personal projects (Git history browsing + informative commit summaries has done the job well enough for me), but I can see why others might enjoy it.

[lhorie]

👍 from me @tivac

[tivac]

Last bit of build automation is #1741, the release process thing is a potentially bigger question.

I vote that we release 1.1.0 on Monday, March 27th. I'm happy to do that work around 9:30AM PDT.

Any concerns @lhorie @isiahmeadows @pygy? I don't see any issues in that milestone that are blocking the release.

Also just to clarify, anybody that can merge and tag a commit on master can push a release to NPM. It's all automated via Travis. It'll use my creds so I get to take credit for your hard work (😉) but I promise you don't need me around.

[pygy]

Great, thanks for adding this :-)

Since it may be needed for me to do releases at some points, I'd rather be sure I understand everything...

Is the manual description of the GH release to be added through the Web interface, after the fact?

Also, Is suppose the -m "v%s" option is there to add a nicer commit message, but I don't understand how it works :-/

[tivac]

Github Release description: Yes, there's no simple way to do that currently.

NPM version -m arg: It makes the git tag/commit message be v1.1.0 instead of just 1.1.0, the %s is just an interpolated value that is replaced with the new version string.

I don't like having to have folks remember to do that, so I'm contemplating making a release script as an alias that always passes that argument, so instead of

npm version minor -m "v%s" you would do npm run release minor.

Thoughts?

[barneycarroll]

Does this imply that docs publications are locked to version releases?

[tivac]

No, docs will auto-build and deploy to the gh-pages branch on any push to master.

http://mithril.js.org does not currently use the auto-published gh-pages branch from lhorie/mithril.js, but that is a relatively trivial change on @lhorie's part once the build changes are integrated AFAIK.

[tivac]

I'm going to cherry-pick my changes to .travis.yml and package.json onto master in my fork and see if I can get things behaving well so that we can test some of the documentation bits before integrating for 1.1.0.

[pygy]

+1 for npm run release X, and thanks for the details :-)

[tivac]

@pygy Yeah I agree that's nicer, 9c8cc8364364736d1d6a40961cc62591e04f0dd3

Documenting it now.

... and done. 4d928d4493310459451992d18e8091c47a6ffb08

[tivac]

Just pushed the doc generation bits (and other build-y stuff) to lhorie/master. Here goes nothing!

[tivac]

https://lhorie.github.io/mithril.js/

So any pushes to lhorie/master will update lhorie/gh-pages which Github will automatically publish.

Since the CNAME file is in place it should be a matter of @lhorie changing the source of http://mithril.js.org to point to the new location and the site will be all set :+1:

[isiahmeadows]

@tivac I'm okay with the proposed date, but I feel 1.1 should wait for this issue to be resolved, since it's clearly an (unintended) break of otherwise reasonable functionality, and it's unclear how this relates to our semver-ish approach. But other than that, I'm okay with that date.

[tivac]

All of this is in and worked for @pygy when cutting 1.1.1 so I'm closing this issue.

👏🏻