Open
Description
Currently, we don't officially support installation via Git, but projects that are attempting to install via Git were required to build assets, via our build_py override. See #1037 and the #1039 temporary fix for some background.
We hit a number of issues supporting installation from Git:
- We have no control over packaging
- Users get an inconsistent experience, as core team treats releases as canonical versions, not
masterbranch - PR merge conflicts on every PR and PR change
- Installation via Git is mostly historical, we should solve user issues with unreleased fixes using development releases.
#1039 temporarily reverted customization of the package build process. There was a source package issue also in #1014 that is unrelated to removing package build override in #1039.
Work
- Create a warning about Git installation deprecation. Detect when building from source or when using a non-release version of the theme. Perhaps there is something we can do with package version here?
- Document deprecation
- Notes on deprecation change
- How we recommend using the theme for given use cases:
- Users installing as a submodule to override SASS or for some unknown reason
- Maintain your own fork against a Git tag, not master
- Users installing via Git directly to get latest branch
- Use RC packages instead
- Users installing as a submodule to override SASS or for some unknown reason
- Release plan for deprecation
Design decisions
- How to technically detect a direct installation at Sphinx build time?
- What additional use cases are we concerned about?
- How do we release backwards incompatible changes?
- Initial change to announce deprecation
- Final deprecation. Do we lump this in with Bootstrap changes?
Activity