Proposal for Pinax Distribution Versioning #84

Open
jtauber opened this Issue Aug 10, 2015 · 25 comments

Comments

Projects
None yet
5 participants
@jtauber
Member

jtauber commented Aug 10, 2015

Unlike monolithic open source projects like Django or Python, Pinax is collection of separately developed components with complex dependency relationships. In many respects, it's more akin to something like Ubuntu than a project like Django.

I'm proposing we do (potentially time-based) releases of "Pinax distributions", so there'd be (to borrow from Ubuntu's numbering) a "Pinax 16.4" which would just be a certain combination of apps, themes, and starter projects.

This would enable us to have a support policy, a minimum bar for documentation and localization, etc that just applies at the "distribution" level, not the individual app level.

Work could freely happen on apps, themes, and starter projects at any time but there'd be some documented process and timeline (TBD) to snapshot particular versions of each of these components to become a versioned Pinax distribution.

@paltman

This comment has been minimized.

Show comment
Hide comment
@paltman

paltman Aug 10, 2015

Member

👍

Member

paltman commented Aug 10, 2015

👍

@jtauber

This comment has been minimized.

Show comment
Hide comment
@jtauber

jtauber Aug 10, 2015

Member

one requirement of a pinax distribution release is documenting how to upgrade

Member

jtauber commented Aug 10, 2015

one requirement of a pinax distribution release is documenting how to upgrade

@jtauber

This comment has been minimized.

Show comment
Hide comment
@jtauber

jtauber Aug 10, 2015

Member

so rather than a combinatorial explosion of upgrade instructions, we'd just publish upgrade instructions for each distribution

Member

jtauber commented Aug 10, 2015

so rather than a combinatorial explosion of upgrade instructions, we'd just publish upgrade instructions for each distribution

@brosner

This comment has been minimized.

Show comment
Hide comment
@brosner

brosner Aug 10, 2015

Member

One of the larger problems I find I face when working on apps is how we version them. With our move to semver this becomes a non-issue. Here's a current brain dump of my line of thinking including some questions.

The various changes we make to repos are:

  • features (both backward-compatible and incompatible)
  • bug fixes (both backward-compatible and incompatible)

Based on the @paltman description of how he releases Pinax apps we have:

X.Y.Z

  • where X is bumped when a change(s) land that break backward compatibility or are very large (chances are pretty high they are breaking)
  • where Y are new features that don't break any compatibility.
  • and where Z are bug fixes

Security patches would likely fall in a Z bump, but in the rare case of a backward-incompatible change to fix a security bug, do we bump X or Z? I suppose following this strictly, we should bump X.

Once an app is tagged to a distribution that has a support policy we need to consider how the versioning works there too. Any changes to the version pinned to a distribution are going to backward-compatible, but we need to consider the cases where a change must be made that is backward-incompatible (likely in the name of security.)

We'll need to come up with a git flow for this. @paltman if you already have one, I'd love to hear about it. I feel it should be a simple branching and tagging process that corresponds to distribution versions as I don't think we'll have any support policies for individual apps outside of what we do with distributions.

App versions should be PEP 440 compatible. This is easy enough, but we do want to consider the version of unreleased code. Let's say a maintainer adds a new feature and releases it. When did the maintainer update the version in the repo? Historically we bump the version right before the release to the correct released version then once after the release to indicate development towards the next release. What does the latter version look like? I am thinking if we release 1.0 of X then the next version after release is 1.1.dev1 then 1.1 or 2.0 given the kind of changes after 1.0. This ensures that if a git repo is installed with -e we have a unique version outside of the released versions.

Member

brosner commented Aug 10, 2015

One of the larger problems I find I face when working on apps is how we version them. With our move to semver this becomes a non-issue. Here's a current brain dump of my line of thinking including some questions.

The various changes we make to repos are:

  • features (both backward-compatible and incompatible)
  • bug fixes (both backward-compatible and incompatible)

Based on the @paltman description of how he releases Pinax apps we have:

X.Y.Z

  • where X is bumped when a change(s) land that break backward compatibility or are very large (chances are pretty high they are breaking)
  • where Y are new features that don't break any compatibility.
  • and where Z are bug fixes

Security patches would likely fall in a Z bump, but in the rare case of a backward-incompatible change to fix a security bug, do we bump X or Z? I suppose following this strictly, we should bump X.

Once an app is tagged to a distribution that has a support policy we need to consider how the versioning works there too. Any changes to the version pinned to a distribution are going to backward-compatible, but we need to consider the cases where a change must be made that is backward-incompatible (likely in the name of security.)

We'll need to come up with a git flow for this. @paltman if you already have one, I'd love to hear about it. I feel it should be a simple branching and tagging process that corresponds to distribution versions as I don't think we'll have any support policies for individual apps outside of what we do with distributions.

App versions should be PEP 440 compatible. This is easy enough, but we do want to consider the version of unreleased code. Let's say a maintainer adds a new feature and releases it. When did the maintainer update the version in the repo? Historically we bump the version right before the release to the correct released version then once after the release to indicate development towards the next release. What does the latter version look like? I am thinking if we release 1.0 of X then the next version after release is 1.1.dev1 then 1.1 or 2.0 given the kind of changes after 1.0. This ensures that if a git repo is installed with -e we have a unique version outside of the released versions.

@jtauber

This comment has been minimized.

Show comment
Hide comment
@brosner

This comment has been minimized.

Show comment
Hide comment
@brosner

brosner Aug 10, 2015

Member

I've read semver before, but thanks for smacking me with a refresher. It looks like I largely hit the nail on the head. The answer to the security change versioning when the change is backward-incompatible seems to be to just bump the major version. However the question remains on how this is handled at the distribution level if changes happened to the app after the tagged distribution version.

The only thing that is incompatible with my proposal are the build metadata. The specified way in semver is not PEP 440 compatible. I think we should stick with my proposal so we have correctly ordered versioning.

Member

brosner commented Aug 10, 2015

I've read semver before, but thanks for smacking me with a refresher. It looks like I largely hit the nail on the head. The answer to the security change versioning when the change is backward-incompatible seems to be to just bump the major version. However the question remains on how this is handled at the distribution level if changes happened to the app after the tagged distribution version.

The only thing that is incompatible with my proposal are the build metadata. The specified way in semver is not PEP 440 compatible. I think we should stick with my proposal so we have correctly ordered versioning.

@paltman

This comment has been minimized.

Show comment
Hide comment
@paltman

paltman Aug 11, 2015

Member

I only ever bump release number right before cutting the release to PyPI as I never know if the next release is going to be X, Y, or Z. After release, I don't bump anything. I do tag with the version number and push the tag, to make it easier to track release diffs and to be an easy to find SHA to branch from should we need to patch a release.

Now, I haven't been fully consistent with the tagging and should be better about it but this process has served me well. I often pip install -e to work on apps but the non-unique version number never gets in my way as part of the process of working on an app, is I just pip uninstall <package_name> first.

Member

paltman commented Aug 11, 2015

I only ever bump release number right before cutting the release to PyPI as I never know if the next release is going to be X, Y, or Z. After release, I don't bump anything. I do tag with the version number and push the tag, to make it easier to track release diffs and to be an easy to find SHA to branch from should we need to patch a release.

Now, I haven't been fully consistent with the tagging and should be better about it but this process has served me well. I often pip install -e to work on apps but the non-unique version number never gets in my way as part of the process of working on an app, is I just pip uninstall <package_name> first.

@brosner

This comment has been minimized.

Show comment
Hide comment
@brosner

brosner Aug 11, 2015

Member

It doesn't matter what the next release is going to be. It just needs to be greater than the current release and less than the next release. X.Y.Z.devN is perfect for that. N will always be 1 in our case.

It's more than just our workflow with the version. If a user is using a development version, but the versions string is wrong it can get confusing in error reports. Also, it bothers me that the version string is extremely misleading.

I had brought this up before and we did agree to it (hence why I said historically.) I guess we all didn't implement it in our workflows. ;-)

Member

brosner commented Aug 11, 2015

It doesn't matter what the next release is going to be. It just needs to be greater than the current release and less than the next release. X.Y.Z.devN is perfect for that. N will always be 1 in our case.

It's more than just our workflow with the version. If a user is using a development version, but the versions string is wrong it can get confusing in error reports. Also, it bothers me that the version string is extremely misleading.

I had brought this up before and we did agree to it (hence why I said historically.) I guess we all didn't implement it in our workflows. ;-)

@paltman

This comment has been minimized.

Show comment
Hide comment
@paltman

paltman Aug 11, 2015

Member

But in your example above you say after releasing 1.0 you'd update the version number to 1.1.dev1, how do you know it's going to be 1.1 (a feature) versus 1.0.1 a bug fix as the next release? Seems wrong to do 1.1.dev1 and then do a bug fix and release 1.0.1.

Member

paltman commented Aug 11, 2015

But in your example above you say after releasing 1.0 you'd update the version number to 1.1.dev1, how do you know it's going to be 1.1 (a feature) versus 1.0.1 a bug fix as the next release? Seems wrong to do 1.1.dev1 and then do a bug fix and release 1.0.1.

@brosner

This comment has been minimized.

Show comment
Hide comment
@brosner

brosner Aug 11, 2015

Member

You don't ever release 1.1.dev1. It is just to give the code in the repository a different version than a released version. So, there's nothing wrong about it. It doesn't have to be 1.1.0.dev1. If 1.0.1.dev1 makes it feel less wrong then we can go with that.

Member

brosner commented Aug 11, 2015

You don't ever release 1.1.dev1. It is just to give the code in the repository a different version than a released version. So, there's nothing wrong about it. It doesn't have to be 1.1.0.dev1. If 1.0.1.dev1 makes it feel less wrong then we can go with that.

@nealmcb nealmcb referenced this issue in pinax/pinax-starter-projects Nov 7, 2015

Closed

How do we upgrade a site to a newer Pinax release? #4

@jtauber

This comment has been minimized.

Show comment
Hide comment
@jtauber

jtauber Jan 6, 2016

Member

I'm wondering if the way forward on this is to shoot for, say, a 16.4 release with a very small subset of starter projects and their apps. Perhaps even just zero and account.

I think the discussion questions are:

  1. what date do we shoot for? April 2016?
  2. what starter projects and apps do we include?
  3. what state do the apps and projects need to be in in terms of tests, documentation to be included?
  4. what should the deadlines leading up to the final release?
Member

jtauber commented Jan 6, 2016

I'm wondering if the way forward on this is to shoot for, say, a 16.4 release with a very small subset of starter projects and their apps. Perhaps even just zero and account.

I think the discussion questions are:

  1. what date do we shoot for? April 2016?
  2. what starter projects and apps do we include?
  3. what state do the apps and projects need to be in in terms of tests, documentation to be included?
  4. what should the deadlines leading up to the final release?
@jtauber

This comment has been minimized.

Show comment
Hide comment
@jtauber

jtauber Jan 6, 2016

Member

I wonder if it's reasonable to say that the apps/themes have to be feature complete in February and the starter projects feature complete in March.

Member

jtauber commented Jan 6, 2016

I wonder if it's reasonable to say that the apps/themes have to be feature complete in February and the starter projects feature complete in March.

@jtauber

This comment has been minimized.

Show comment
Hide comment
@jtauber

jtauber Jan 6, 2016

Member

Perhaps we decide 3 and 4 before 2 and the starter projects and apps included are those that make the cut in time.

Member

jtauber commented Jan 6, 2016

Perhaps we decide 3 and 4 before 2 and the starter projects and apps included are those that make the cut in time.

@paltman

This comment has been minimized.

Show comment
Hide comment
@paltman

paltman Jan 9, 2016

Member

@jtauber i think this is a reasonable approach. i think documentation is paramount for anything we want to consider in a release. it's hard to have a good metric for doc completeness but I think it's easy to know when you see it.

Member

paltman commented Jan 9, 2016

@jtauber i think this is a reasonable approach. i think documentation is paramount for anything we want to consider in a release. it's hard to have a good metric for doc completeness but I think it's easy to know when you see it.

@jtauber

This comment has been minimized.

Show comment
Hide comment
@jtauber

jtauber Jan 12, 2016

Member

We will provide a documentation path for upgrades only between releases (e.g. 16.10 will explain how to upgrade from 16.4 but we make no make commitment to provide upgrades from anything else)

Member

jtauber commented Jan 12, 2016

We will provide a documentation path for upgrades only between releases (e.g. 16.10 will explain how to upgrade from 16.4 but we make no make commitment to provide upgrades from anything else)

@jtauber

This comment has been minimized.

Show comment
Hide comment
@jtauber

jtauber Jan 12, 2016

Member

16.4 apps need to support Django 1.8 and Django 1.9 but 16.4 projects will use Django 1.9 out of the box

Member

jtauber commented Jan 12, 2016

16.4 apps need to support Django 1.8 and Django 1.9 but 16.4 projects will use Django 1.9 out of the box

@jtauber

This comment has been minimized.

Show comment
Hide comment
@jtauber

jtauber Jan 12, 2016

Member

This is a list of possible apps for inclusion.

  • pinax-theme-bootstrap
  • django-user-accounts
  • metron
  • pinax-eventlog
  • pinax-waitinglist
  • pinax-blog
  • pinax-stripe
  • pinax-pages
  • pinax-wiki
  • pinax-boxes
  • pinax-forums
  • pinax-referrals
  • pinax-submissions
  • pinax-teams
  • pinax-types
  • pinax-documents
  • pinax-notifications
  • pinax-invitations
  • pinax-images
  • pinax-testimonials
  • pinax-likes
  • pinax-ratings
  • pinax-messages
  • pinax-points
  • brabeion
  • kairios
  • formly
  • django-announcements

(pinax-cli)

Member

jtauber commented Jan 12, 2016

This is a list of possible apps for inclusion.

  • pinax-theme-bootstrap
  • django-user-accounts
  • metron
  • pinax-eventlog
  • pinax-waitinglist
  • pinax-blog
  • pinax-stripe
  • pinax-pages
  • pinax-wiki
  • pinax-boxes
  • pinax-forums
  • pinax-referrals
  • pinax-submissions
  • pinax-teams
  • pinax-types
  • pinax-documents
  • pinax-notifications
  • pinax-invitations
  • pinax-images
  • pinax-testimonials
  • pinax-likes
  • pinax-ratings
  • pinax-messages
  • pinax-points
  • brabeion
  • kairios
  • formly
  • django-announcements

(pinax-cli)

@jtauber

This comment has been minimized.

Show comment
Hide comment
@jtauber

jtauber Jan 12, 2016

Member

So the plan is:

  • get a subset of these apps into a good state by end of February
  • get a subset of those apps into starter projects and get those starter projects in a good state by end of March
  • release 16.4 in April!
Member

jtauber commented Jan 12, 2016

So the plan is:

  • get a subset of these apps into a good state by end of February
  • get a subset of those apps into starter projects and get those starter projects in a good state by end of March
  • release 16.4 in April!

@jtauber jtauber referenced this issue in pinax/symposion Jan 21, 2016

Open

Document backwards-incompatible changes. #121

@paltman paltman referenced this issue in pinax/pinax-announcements Jan 24, 2016

Closed

Release a new version #25

@arthur-wsw

This comment has been minimized.

Show comment
Hide comment
@arthur-wsw

arthur-wsw Feb 22, 2016

For apps i have already contributing on, i think following apps could be include in 16.4 release

  • django-user-accounts
  • pinax-images
  • pinax-likes
  • pinax-ratings
  • pinax-messages
  • pinax-announcements
  • pinax-teams

I didn't know for the others one because i've never test any of them at the time.

For apps i have already contributing on, i think following apps could be include in 16.4 release

  • django-user-accounts
  • pinax-images
  • pinax-likes
  • pinax-ratings
  • pinax-messages
  • pinax-announcements
  • pinax-teams

I didn't know for the others one because i've never test any of them at the time.

@jtauber

This comment has been minimized.

Show comment
Hide comment
@jtauber

jtauber Feb 22, 2016

Member

@arthur-wsw thanks

@paltman @brosner are there any in my list that you think are definitely "no way will they be ready"? i.e. a -1 vote. That way we can immediately shorten the list under consideration.

Actually we almost could do with symposion-style voting / comments where the "submissions" are the apps.

Member

jtauber commented Feb 22, 2016

@arthur-wsw thanks

@paltman @brosner are there any in my list that you think are definitely "no way will they be ready"? i.e. a -1 vote. That way we can immediately shorten the list under consideration.

Actually we almost could do with symposion-style voting / comments where the "submissions" are the apps.

@jtauber

This comment has been minimized.

Show comment
Hide comment
@jtauber

jtauber Feb 27, 2016

Member

Based on the voting these are the current app candidates for the 16.04 distribution:

  • pinax-cli
  • pinax-theme-bootstrap
  • django-user-accounts
  • pinax-webanalytics
  • pinax-eventlog
  • pinax-waitinglist
  • pinax-blog
  • pinax-stripe
  • pinax-types
  • pinax-documents
  • pinax-notifications
  • pinax-invitations
  • pinax-images
  • pinax-testimonials
  • pinax-likes
  • pinax-messages
  • pinax-calendars
  • pinax-announcements

Note this doesn't mean that work on other apps won't continue. Just that only the above are contenders for inclusion in the April distribution. Note also I say "contenders". Just because an app is in this list doesn't mean it will be included in 16.04. The apps still need to be used in a starter project that is itself accepted for inclusion.

Member

jtauber commented Feb 27, 2016

Based on the voting these are the current app candidates for the 16.04 distribution:

  • pinax-cli
  • pinax-theme-bootstrap
  • django-user-accounts
  • pinax-webanalytics
  • pinax-eventlog
  • pinax-waitinglist
  • pinax-blog
  • pinax-stripe
  • pinax-types
  • pinax-documents
  • pinax-notifications
  • pinax-invitations
  • pinax-images
  • pinax-testimonials
  • pinax-likes
  • pinax-messages
  • pinax-calendars
  • pinax-announcements

Note this doesn't mean that work on other apps won't continue. Just that only the above are contenders for inclusion in the April distribution. Note also I say "contenders". Just because an app is in this list doesn't mean it will be included in 16.04. The apps still need to be used in a starter project that is itself accepted for inclusion.

@jtauber

This comment has been minimized.

Show comment
Hide comment
@jtauber

jtauber Feb 27, 2016

Member

Next steps?

  1. if anyone has a problem with the above 18 (either an inclusion or omission) raise a flag ASAP!
  2. if there is any work in progress on any of these apps it needs to quickly be triaged and anything likely to be unstable should be punted
  3. we do releases of all the above apps (if needed) and note the release number that is a candidate for 16.04
  4. we quickly identify gaps in starter projects and get working on them to make sure every candidate app above is well represented amongst the starter projects

I'll start a spreadsheet to track some of this.

Member

jtauber commented Feb 27, 2016

Next steps?

  1. if anyone has a problem with the above 18 (either an inclusion or omission) raise a flag ASAP!
  2. if there is any work in progress on any of these apps it needs to quickly be triaged and anything likely to be unstable should be punted
  3. we do releases of all the above apps (if needed) and note the release number that is a candidate for 16.04
  4. we quickly identify gaps in starter projects and get working on them to make sure every candidate app above is well represented amongst the starter projects

I'll start a spreadsheet to track some of this.

@jtauber

This comment has been minimized.

Show comment
Hide comment
@jtauber

jtauber Feb 27, 2016

Member

PROPOSAL: any candidate app that has a pre-1.0 release number is released as 1.0 once an initial sanity check is done.

Member

jtauber commented Feb 27, 2016

PROPOSAL: any candidate app that has a pre-1.0 release number is released as 1.0 once an initial sanity check is done.

@jtauber

This comment has been minimized.

Show comment
Hide comment
@jtauber

jtauber Feb 27, 2016

Member

Okay, I've set up a spreadsheet to track readiness: https://docs.google.com/a/jtauber.com/spreadsheets/d/1jyFeFpl7BhWiVyok5Lzf-MbNy6_brJQIyAOzVw3wx7o/edit?usp=sharing

There are a lot of issues to triage!

Member

jtauber commented Feb 27, 2016

Okay, I've set up a spreadsheet to track readiness: https://docs.google.com/a/jtauber.com/spreadsheets/d/1jyFeFpl7BhWiVyok5Lzf-MbNy6_brJQIyAOzVw3wx7o/edit?usp=sharing

There are a lot of issues to triage!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment