Documented the development and release models

[inclement]

Added some documentation about our new git flow structure, and documented the release checklist proposed at #1836.

I propose that once everyone is happy with this, I'll merge the PR, then immediately create the develop branch and the first release branch. We can tidy up any procedural issues in that first release, including making sure the release checklist works okay.

The only real unanswered question is what CalVer format to use. Is there any reason not to go with YYYY.MM.DD? Is some other option more normal (or more pep-440 compatible)?

[ghost]

Actually, git flow doesn't necessarily work with pull requests as far as I'm aware. It usually incorporates release branches and hotfix branches as far as I remember, as well as feature branches with a naming scheme - none of which we really do.

Therefore I think mentioning git flow is more distracting and confusing than helpful. I would describe what python-for-android does from what I can see as "development on develop branch with a pull request flow and releases on the master branch", I would recommend just not mentioning git flow at all since to me it appears to be too different

[inclement]

I put the instructions about the pull request because it seemed like a convenient way to centralise release discussion and see all the changes at once. I thought that the proposed branching structure would be exactly what git flow uses, but maybe I've misunderstood something?

For the feature branches, I didn't write about it because we do almost all development in personal branches in our own forks. The naming seemed like a minor point compared to the main development structure, but I'm happy to rethink it. I had imagined that we would be more formal about naming them feature/whatever style if pushed to this repo, although I didn't write that down.

Similarly with hotfix branches, I was imagining that we'd use the git flow structure for that, but didn't bother documenting the details for now.

[ghost]

@inclement companies who use git flow usually don't use personal repos. that's simply a slightly different approach, and gitflow also uses hotfix branches and a separate forked off branch for each release in preparation and other things - it's just way more than we do. so basically it has some similarities but it's just not an exact match, which is why I recommend not mentioning it

Edit: oh right, you did propose release branches. so it's not that far off I suppose, but still, I've seen pull requests-based approaches with a different name so I'm not sure it might not be a little confusing. maybe it's just me though 🤷‍♀️

[inclement]

and gitflow also uses hotfix branches and a separate forked off branch for each release in preparation and other things - it's just way more than we do

Right, but I'm proposing we do start doing this (per the instructions). Do you think it's overkill?

Edit: I'm not at all wedded to the git flow name though, just a nice procedure :p. I'd like to link the document for reference, but I could certainly remove the emphasis on git flow itself.

[ghost]

@inclement hmm release branches might be, the reason they're usually done is so that pull request merging and such can continue while the release is prepared. but we don't have a huge pull request volume anyway, and it's normal that we delay them often (not necessarily a bad thing) so I don't see a problem just not merging things for 2 -3 days while we put together a release unless it fixes something in the release

if you want to do it anyway though I don't object, I just think at our current dev speed preparing the release on master could work well enough. of course that'd make the master slightly more unstable, but it would still be more stable than most master branches of most projects on github 😄

[inclement]

Thanks @Jonast. I've pushed a change to de-emphasise git flow except as a reference.

I'd like to leave the release branch stuff in there to see how it goes. We can always relax this if that turns out to be easier, I'm not one for unnecessary procedure. For now I like the idea because it seems like it should be straightforward but nice and clear, something that's been an issue in the past when release preparation has dragged on a bit. It's possible I might be overcompensating though, given that those things were my fault in the first place :p

[opacam]

About packaging and pypi upload

We could generate the wheel alongside the tar.gz package like this:

• Install/upgrade setuptools and wheel:
  • python3 -m pip install --user --upgrade setuptools wheel
• Generate distribution archives:
  • python3 setup.py sdist bdist_wheel

And then the twine upload commands would be:

• Install/upgrade twine:
  • python3 -m pip install --user --upgrade twine
• Upload the distribution archives with:
  • twine upload dist/*

Note: notice that the twine command is triggered without python, the latest twine releases comes with a binary

See also:

• Generating distribution archives
• Uploading distribution archives

[opacam]

About calver format, I usuallly prefer the short version of year YY.MM.DD, I don't have strong arguments for this, only that it shortens a little the version, that the version is more homogenous and maybe more readable...but after reading a little the link that @inclement posted about pep 440, I have my doubts about using the format I propose or the initial @inclement's proposal, because they mention the following about date versions in their examples section:

Date based releases, using an incrementing serial within each year, skipping zero:

2012.1
2012.2
2012.3
...
2012.15
2013.1
2013.2
...

So maybe we should take the pep 440 road...

See also: version scheme examples pep 440 compliant

[ghost]

I mean realistically python-for-android might not exist in 90 years, but you never know. I'd rather stick with 4 digit year just to be safe

[AndreMiras]

Nice proposal overall and thanks for opening the discussion guys 👏
I personally like what we have in the proposal. I think sharing git flow for reference is great because it's an improved model and we don't have to maintain a too specific documentation. We also don't have to use the complete model with hotfixes... but I think master, develop, (feature) and release as described is completely fine.
As for the version I'm fine with YYYY.MM.DD 👍

[opacam]

Thanks @inclement !!