Update Installation docs to match the tutorial.

[cullerton]

Hey Disko,

This branch removes your |version| variable in the Installation docs, and uses the github master branch instead. This allows someone to follow the Installation and Tutorial together.

I'm not sure if you want/need this right now. We need to figure out what to do long-term though.

Do with it what you wish :)

Mike

[dnouri]

The install docs should describe how to install the latest stable version, not Git master.

[disko]

This means we'd have to change that with every release, would be nice if we could avoid that.

The way I'm doing this in other projects is using gitflow, which is a set of conventions for branching and merging that comes bundled with a git command to enforce these conventions in a super convenient way [1, 2]. There you have a "production" branch which is always identical to the latest released version. To minimize the implications on collaborating with other users who don't use gitflow, I use different names though: master is my development branch and production is my release branch (should probably better named release).

As I'm using it everywhere anyway, I'd also recommend it for the Kotti main repo. To be clear: as it's only conventions, no one would be actually required to use it.

[1] https://github.com/nvie/gitflow
[2] http://nvie.com/posts/a-successful-git-branching-model/

[cullerton]

This was only a short-term patch to match up installation and tutorial to the new Kotti scaffolding.

Long-term, I believe we need a way to install that does not change when versions change. Maybe a link/tag called current that always points to the current release. That way, folks could always get the current release with the same commands. Something like

pip install -r https://github.../current/requirements.txt
pip install Kotti==current

[dnouri]

Not sure how branch naming or gitflow is related? I also have no idea how |version| was supposed to work before, but is it a template variable? I understand that @cullerton's change is temporary, so it's fine. Let's just not have people install Kotti from the latest bleeding edge in the main install docs, long term.

[disko]

Very briefly: with gitflow you have a branch that is always the same as the latest release (production in my example below). So people can use (and we can instruct them to do so in the docs) that branch to have the latest released version without having to now the version number. You can of course do the same without gitflow, it just automates this convention for you.

Example

Initialize the repo to use gitflow:

(kotti)➜  kotti_addon git:(master) ✗ git flow init

Which branch should be used for bringing forth production releases?
   - master
   - production
Branch name for production releases: [production]

Which branch should be used for integration of the "next release"?
   - master
Branch name for "next release" development: [master]

How to name your supporting branch prefixes?
Feature branches? [feature/]
Release branches? [release/]
Hotfix branches? [hotfix/]
Support branches? [support/]
Version tag prefix? []

Do work on master as usual. When master is ready for a new release do:

(kotti)➜  kotti_addon git:(master) ✗ git flow release start 1.0.0
Switched to a new branch 'release/1.0.0'

Summary of actions:
- A new branch 'release/1.0.0' was created, based on 'master'
- You are now on branch 'release/1.0.0'

Follow-up actions:
- Bump the version number now!
- Start committing last-minute fixes in preparing your release
- When done, run:

     git flow release finish '1.0.0'

Do some "last minute changes", such as increasing the version or some other metadata and publish the release to PyPI:

(kotti)➜  kotti_addon git:(release/1.0.0) ✗ vi setup.py
(kotti)➜  kotti_addon git:(release/1.0.0) ✗ git commit -m "Bump version" setup.py
[release/1.0.0 7a49df1] Bump version
 1 file changed, 1 insertion(+), 1 deletion(-)

(kotti)➜  kotti_addon git:(release/1.0.0) ✗ python setup.py sdist upload
[…]

Here comes the real convenience:

(kotti)➜  kotti_addon git:(release/1.0.0) ✗ git flow release finish 1.0.0
Switched to branch 'production'
Merge made by the 'recursive' strategy.
 setup.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Switched to branch 'master'
Merge made by the 'recursive' strategy.
 setup.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Deleted branch release/1.0.0 (was 7a49df1).

Summary of actions:
- Latest objects have been fetched from 'origin'
- Release branch has been merged into 'production'
- The release was tagged '1.0.0'
- Release branch has been back-merged into 'master'
- Release branch 'release/1.0.0' has been deleted

The remainder of this comment is just for the sake of completness and doesn't directly relate to the initial topic.

gitflow has two more subcommands: one for adding a new feature that is intended to go into master only and one for a hotfix that is intended to go into master and production (and thus a new release).

Start a new feature:

(kotti)➜  kotti_addon git:(master) ✗ git flow feature start more_awesomeness
Switched to a new branch 'feature/more_awesomeness'

Summary of actions:
- A new branch 'feature/more_awesomeness' was created, based on 'master'
- You are now on branch 'feature/more_awesomeness'

Now, start committing on your feature. When done, use:

     git flow feature finish more_awesomeness

Work on the feature branch as usual. Either create a pull request when done or merge the feature into master yourself:

(kotti)➜  kotti_addon git:(feature/more_awesomeness) ✗ git flow feature finish more_awesomeness
Switched to branch 'master'
Updating adf7d23..5d5150c
Fast-forward
 README.rst | 2 ++
 1 file changed, 2 insertions(+)
Deleted branch feature/more_awesomeness (was 5d5150c).

Summary of actions:
- The feature branch 'feature/more_awesomeness' was merged into 'master'
- Feature branch 'feature/more_awesomeness' has been removed
- You are now on branch 'master'

Start a new hotfix:

(kotti)➜  kotti_addon git:(master) ✗ git flow hotfix start 1.0.1
Switched to a new branch 'hotfix/1.0.1'

Summary of actions:
- A new branch 'hotfix/1.0.1' was created, based on 'production'
- You are now on branch 'hotfix/1.0.1'

Follow-up actions:
- Bump the version number now!
- Start committing your hot fixes
- When done, run:

     git flow hotfix finish '1.0.1'

Fix the bug in the hotfix branch, update version number in the package metadata and commit. Then finish the hotfix:

(kotti)➜  kotti_addon git:(hotfix/1.0.1) ✗ git flow hotfix finish 1.0.1
Switched to branch 'production'
Merge made by the 'recursive' strategy.
 setup.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Switched to branch 'master'
Merge made by the 'recursive' strategy.
 setup.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Deleted branch hotfix/1.0.1 (was 22788cf).

Summary of actions:
- Latest objects have been fetched from 'origin'
- Hotfix branch has been merged into 'production'
- The hotfix was tagged '1.0.1'
- Hotfix branch has been back-merged into 'master'
- Hotfix branch 'hotfix/1.0.1' has been deleted

Now either checkout the production branch or the 1.0.1 tag and publish the release to PyPI.

[disko]

Regarding |version|: this is substituted with the version variable from docs/conf.py. This would work only if we took care that RTD doesn't render and publish on changes in master, but only on released tags.

[dnouri]

Ah, understood how the gitflow model is related to the change now. My only reservation with gitflow is that may raise the barrier for contributors. It seems like now there's a convention on top of 'normal' git that I have to understand. You'll say that it's just a convention, and that it makes life easier, but honestly I don't know. Willing to go along though if you're willing to regard yourself as the release manager now. :-)

It would be great if we could get RTD to publish the latest release instead of master always.

[disko]

My only reservation with gitflow is that may raise the barrier for contributors.

Nope. Nothing changes at all for contributors. They don't need to use or even know gitflow. You just need to tell it to use different branch names than it suggests (once, upon initialization). I'd also be fine with being release manager, because it's so easy with gitflow.

Having a production branch as described would also solve the RTD issue as this would be latest on RTD.

[dnouri]

Alright, good job with dodging the release manager question. But I'm fine, let's use it if it's that good. ;-)

[disko]

Huh, dodging? Not at all! I'd be fine taking over if you want...

[dnouri]

My humor is seemingly getting lost in this bug tracker (if it ever existed), sorry for that. I'd say you're the perfect candidate for the role. :-)

[disko]

I'll merge this to at least fix the issue reported in #358. Better have people install latest master than nothing at all. Will be finally resolved as discussed with the next release, which is only blocked by 1 more issue (#320), which I'll start working on today.