Change how we do packaging

[agjohnson]

Currently, PRs are expected to grunt build themselves. This leads to a merge conflict problem when there are multiple PRs open. We should instead be handling build artifacts on release.

The workflow here would be that when it makes sense, a maintainer will release the package, either as a development release or as a prod package. The maintainer will run grunt build, check those artifacts into the repository, the commit will be tagged, and a release to go out to PyPI.

We can't remove storing artifacts as a number of folks pin their theme dependency here. We can remove the requirement that PRs run grunt build, but perhaps find another mechanism for keeping our version on conflict, such as using .gitattributes to use ours on merge.

[jessetan]

Removing the need for PRs to run grunt build is a good idea to reduce merge conflicts. We could add instructions in a PR template

If building and committing the assets to the repo is needed for people who use master instead of a package from Pypi, this can be a periodic task for maintainers or automated using a bot and/or git webhooks.

[agjohnson]

I think a release time process by maintainers makes the most sense. We can think about automating this later perhaps.

We're hoping to shorten the release cycle and make more minor releases with the theme. With that, we can just release more often, generate build assets on release, and perhaps just disregard the use case of running the theme from master -- running from master would effectively just be the same as running from the latest release.

[jessetan]

Keeping the built assets up to date can be done with Travis as following (roughly):

• An after_success block is added to .travis.yml to call a bash script
• The script checks if the commit is not a PR commit and the affected branch is master. This is effectively a check for a merged PR.
• The script installs any dependencies and runs grunt build to create the build artefacts (located in sphinx_rtd_theme/static)
• The script commits these files to master using a properly secured access token

The process for a PR then becomes:

1. Authors creating a PR will be presented with a PR template that instructs them not to include the built assets (although nothing will break if they do)
2. Comments and review
3. PR is merged to master
4. Travis commits built artefacts to master, making master up to date with the changes from the PR

Inspiration:

https://github.com/cvan/webvr/blob/ca0e903/scripts/deploy.sh
https://gist.github.com/domenic/ec8b0fc8ab45f39403dd
https://benlimmer.com/2013/12/26/automatically-publish-javadoc-to-gh-pages-with-travis-ci/

This does not solve the problem of releasing the theme, although it could be expanded to help with automating part of it.

[Blendify]

I like this idea.

[davidfischer]

When I reread the comment from @agjohnson, it sounds to me like he's proposing adding the built files to .gitignore and removing them from the repo (git rm). Then these would need to be built right before a release is made. Correct me if I'm wrong. As he mentions this would mean that users couldn't just use the theme from "master". They would have to use a packaged version.

What @jessetan is proposing sounds more like having an automated way to keep the built artifacts up to date. This would still allow users to use the theme from master but at the cost of some complexity.

If nobody has a strong opinion, I prefer the first approach but not too strongly.

[jessetan]

@davidfischer that's correct. A requirement for the first approach would be to do releases more often. This is also has my preference BTW.

[jessetan]

@agjohnson any update on simplifying or speeding up the release process? Supporting a theme install from master has some drawbacks (e.g. #712)

[davidfischer]

For the record, I'm 👍 on removing built artifacts from the repo and only supporting using released versions (not an install from git master). I don't think releasing frequently is a big burden.

[agjohnson]

I am also 👍 on just git ignore on the whole sphinx_rtd_theme/static/ path and making building assets strictly a release process. I'd like to support a single installation path, so 👍 on that too.

Unfortunately, anyone that hit #712 (myself included) would have broken docs pretty quickly. Our docs do currently state you can git install/submodule install, and I did remove these instructions in a PR, but we were communicating a blessed installation path to users by having this in our docs. So, these users aren't wrong for installing like this.

For now, the webpack work is actually going to revert the font path change (I didn't know this was an issue, and it's odd that we take a stance on fonts, but not our other assets) and all assets will be checked in for the time being. It sounds like we need more of a plan around breaking this workflow first?

Could we detect that the user is running a non-released version (compare a non-release package version? test for a file in the repo and not in release? something else in setup.py?). We'll start by throwig a deprecation warning in sphinx and let this simmer for a couple releases perhaps?