Add documentation

[ceball]

Just a sketch here - please edit in place, add, delete, etc; just thinking out loud.

Commands to learn about what's in my environment

$ autover numpy scipy conda sed
numpy=1.12.1                   # /Users/cball/anaconda3/lib/python3.6/site-packages/numpy
scipy=0.19.0                   # /Users/cball/anaconda3/lib/python3.6/site-packages/scipy
sed=unknown                    # /usr/bin/sed

Add/edit my package's version info?

Run a command? Edit setup.py, __init__.py? Add a file?

$ autover ??? mypackage

Commands to learn about autover itself

$ autover --version
?
$ autover --help
?

[ceball]

I'm most concerned about documentation on (1) how to add autover to a project, and (2) how to use autover when making a release.

I'm personally not worried if (1) is manual and/or difficult because it only has to be done once.

I hope (2) could be as short as something like git tag -a v1.2.3 -m "Release..." && python setup.py sdist && conda build conda.recipe (where the second command might instead be git push --tags because packaging is set up on CI).

[jlstevens]

Right now it should be as simple as you hope for 2. As for point 1, more explicit documentation is a good idea but there is already a fair bit of information in the module docstring and class docstring.

[ceball]

Something I haven't given a lot of thought to, but which we should probably decide on...

Some projects might want to do "latest master" (continuous) dev packages, while other projects might want to explicitly create dev packages. And do we care about release candidates, etc?

Personally I have really thought only about "finished release" and "latest master" dev packages. I'd be happy with only those. However, I think there are other valid ways to do things, and I'm most concerned about getting automated packaging (so a scheme that is package on demand via pushing git tag would also be ok with me, and indeed I use that myself on some projects - although I prefer just having "latest master" dev packages and not thinking about it).

Is there any conflict here? Should all our projects do the same thing? I can't quite think it through.

In the first case, they would do git tag -a v1.2.3 to release, and then "latest master" package versions would automatically be e.g. v1.2.4.dev1+gSHA, v1.2.4.dev2+gSHA, etc, until the next release (predicted to be 1.2.4).

In the second case, they could do git tag -a v1.2.3 to release and then e.g. git tag -a v1.2.4.dev1 when ready to create a new 1.2.4.dev1 package (any number of commits later). Or git tag -a v1.2.4.rc1, or whatever.

[jbednar]

I think that between full releases each project should choose either (a) continuous dev releases (one per commit since previous real release), or (b) explicit dev releases (one per explicit tag that says "dev" in it, where the person who tags is responsible for incrementing the dev release number each time they tag). If you try to mix the two in between real releases, everyone is going to get confused.

With that in mind, I agree with your first and second case descriptions, but note that only the first case has been fully specified here. In the first case, it's clear what the version is for every commit, because the commit number is encoded into the version string directly. In the second case, you've defined versions only for the explicitly tagged cases, which by definition is all you need for packaging, but for ordering and consistency we still need to declare what the version is between tagged versions (e.g. when getting the source directly from git). The problem is, I don't know how we would know from the tags that we are in the second case until a dev version is explicitly tagged; up until then it's identical to the first case, and thus would get versions like 1.2.4dev1+gSHA that would be confusing with a later explicitly tagged 1.2.4dev1 that could be from months later.

So would autover need to be configured to be in this second case as a separate mode or option like "append_commit_count=True", telling it to generate versions like 1.2.3-M-gSHA before the first dev release for a commit count of M, then ones like 1.2.4dev1-M-gSHA after an explicitly tagged 1.2.4dev1? I.e., in this second mode the commit count does not go into "devN", it goes separately as M, and is omitted for the real and dev releases.

[jlstevens]

When you say:

(a) continuous dev releases (one per commit since previous real release), o

I assume you mean 'one per commit to master if squash merging PRs' or alternatively 'one per PR merged to master'. Unless you mean building for testing purposes on every commit but not uploading the build packages?

If you try to mix the two in between real releases, everyone is going to get confused.

Agreed. I think having those two modes supported (but mutually exclusive) should be sufficient.

I think I understand the problem you are describing though maybe it can be solved by running 'git describe' twice - once to match 'dev' tags and once without. The idea would be to use the dev tag only if you are zero commits past it, otherwise to use whatever other 'normal' intermediate versioning scheme we use. I've not yet investigated but this seems like it might be plausible and not too hard...

This is a bit different from your suggestion - I think having dev versions with post commit counts relative to those is confusing. I think I prefer just dev1, dev2, dev3 and whatever format we use for everything else in between releases...

[jbednar]

By 'commit' I mean 'commit to master', personally; I don't want any package builds for PRs. Maybe someone does, but I think that would get very confusing.

I think I understand the problem you are describing though maybe it can be solved by running 'git describe' twice - once to match 'dev' tags and once without. The idea would be to use the dev tag only if you are zero commits past it, otherwise to use whatever other 'normal' intermediate versioning scheme we use.

I don't think that works, because the proposed 'normal' intermediate scheme is indistinguishable from an explicitly tagged dev release. I.e., if the most recent tagged release was 1.2.3 and there has been one commit, the version according to the 'normal' intermediate scheme will be 1.2.4dev1.
That won't work because it's the same version you'll get if someone 50 commits later tags an explicit dev release 1.2.4dev1. Having those two match violates the principle that versions from master should all compare properly to each other to indicate which is newer. That's why the second case needs to list the post-commit counts separately in the version; it's the only way to keep them distinct and sorting properly as far as I can see.

[jlstevens]

Ok. I see what you mean and I think you are right.

So would autover need to be configured to be in this second case as a separate mode or option like "append_commit_count=True"...

Why have a flag for this? Why shouldn't what you propose just be the normal behavior?

[jbednar]

I think it has to be a flag (though I hope I'm wrong, as a flag makes it more complex), because we have to choose between showing the commit count as N in devN, or as in ...-N. If we choose the commit count to show up in devN, then we can't tag explicit dev releases. If we want to tag explicit dev releases, we have to put the commit count into ..-N, not the dev release number, or else we'll get mixed up versions.

[jlstevens]

I believe autover is finally ready to document. It is nice to have /examples/pkg_bundle and /examples/pkg_depend to make things concrete.

There are now lots of ways of using autover so I'll just make some notes about how to integrate it into a project:

1. There are two short functions to copy into setup.py. They don't ever need changing: you only need to set the reponame in the function call to set the setup.py version.
2. You need .version to be included in the package. This can be done via setup.py or in the MANIFEST.
3. As with anything involving git archive support, you need need to set .gitattributes and track that file.
4. (Optional) You probably want to add .version to your .gitignore and probably version.py as well (unless you explicitly chose to embed it).

I think that summarizes setting things up to use autover. Actually using it (setting tags, auto-packaging and releasing etc) also requires docs but I'm not going to start that just yet.