Foundation-sites: Branches, releases and supported versions

[ncoden]

I have some remarks to make about the Foundation's release process and the way we use git branches. Poke @zurb/yetinauts.

Scheduled releases

Currently, we we have scheduled releases, you can find them on the roadmap. The next patch version (v6.3.1) is planned for mi-January, the next minor version (v6.4) for May, and the next major version (v7) will come in November, even if it is very difficult to estimate this.

I totally understand the benefits of planning the changes we will make and the new features we will add. It helps to make the participations more accessible, to be more synchronized between contributors, and maybe it helps the users of Foundation to be prepared for breaking changes. However, I think having this changes on a Calendar is not a good idea.

• There is a lot of new features and safe patches (sometimes very important fixes) that can't be released as soon as we have a stable version. Look at all the bugs fixes in the list of PRs or that have alreary been merged. They will not be publicly available before mid-January, even if we are certain they are stable and safe.
• It sorts minor and patches releases. When the next scheduled release is a _minor_ version, all the bug fixes will not be released before we checked the minor (sometimes breaking) changes are safe, even if they are unrelated with the fixes. We experienced that recently with v6.3.0, where we released some fixes made more than 8 months ago.
• For the same reason, when the next scheduled release is a _patch_ version, we are pushed to include into it breaking fixes, and even sometimes breaking minor changes (a new feature or refactor required to fix a bug, or a simple change planned for the next release without checking of what type of release it would be). An example of this is: https://github.com/zurb/foundation-sites/issues/9507.
• If we discover a bug difficult to resolve just before a release (or in a Release Candidate), we are not pushed to resolve it in a proper manner. A version must be released, time passes, so we are more likely to keep a dirty work around. I think https://github.com/zurb/foundation-sites/pull/9469 is a very good example of this problem (I'm not proud of this PR at all).

For these reasons, I think we should move to a more fluid management of future fixes and features. Here some proprosals I have to do this, but I am open to any other proposition:

1. Release patch and minor versions quickly.
   Within one to three week for patches and within one to three months for breaking minor changes and new features. Try to move out from the "marketing release" approach for at least minor releases.
2. Do not except some fixes or features to be introduced in the next release.
   Work on patches in priority, but release a version as soon as it is stable, even with known and unfixed bugs from the previous releases.
3. Do not introduce breaking changes in a patch version .
   If a bug fix require a breaking change (other than the bugged behavior itself), do not introduce it in a patch version. If a bug fix require a breaking change to keep the codebase maintainable, make a basic patch for the next patch version and the previous compatible versions, and prepare a proper patch with breaking changes for the next breaking release. See the git flow below.
4. Do not release an unstable version.
   Do not introduce workarounds, unless as hotfixes because of a sever bug have been released on production or the development process is broken. Explicitly specify workaround and release a stable patch version as soon as possible. For all others cases, wait for a real fix or remove the unstable feature if it is new.

Versions support

Currently, we do not support older versions. I do not know for sure for before v6, but it seems we have never released patch versions for previous minor/major versions. We worked on v6.2.x patches, then released the latest fixes in v6.3.0 and recommended to upgrade to it. v6.2.5 was originally planned for 1st December, before being canceled to release v6.3.0 a month sooner.

_Which previous version should we support and how_ is a difficult question, because we must find the good ration between the work we put in it and the usefulness for users. According to me, version support is useful for users for two reasons: not letting an annoying bug and giving time to upgrade. I understand from that three principles:

• We should actively support minor or recent versions. Some users can need the latest fixes while not be able to upgrade to the latest version quickly. There is always problems we cannot predict coming from the way Foundation will be used, and huge changes needed in the user codebase. A migration is never easy, even for minor versions.
• We cannot indefinitely actively support previous versions. It would require a lot of work to check for each bug if it was present and could be fixed in all previous versions, and it would increase the risk of introducing unexpected breaking fixes.
• We should passively support all previous versions. It means we do not create fixes for oldest minor/major versions, but we still accept pull requests and release a patch version time to time. It does not concern a lot of people, but we shouldn't intentionally let bugs in "stable" versions, even if they are old.

To follow these principles, here are some propositions for Foundation's current and future versions:

1. Actively support the two or three latest minor versions.
   It means v6.2 and v6.3 for now, then the two (from 1 to 6 months back) or three (from 2 to 9 months back) latest versions following the release intervals. When a bug is reported, we fix the bug for all the versions we support, by merging the fix if it is compatible and creating a new one if not.
2. Actively support the latest major version for a month.
   It means we could have continued to support v5.5 when v6 was released until December 2015 (even if it seems v5 support was dropped way before v6was released).
3. Always release a patch version.
   When we release a minor/major version, we should release in the same time a patch version for all supported previous versions, containing the bug fixes made while preparing the minor/major version.
4. Inform about the supported versions and support process.
   For now, we actively support v6.2 and v6.3, and do not support previous versions (including Foundation 5), but we still accept pull requests. These informations and the previous ones should be added in the Github issue and pull request messages.

Branches

Currently, we mainly work on the default branch :develop (for "bug fixes") and :v6.x (for "new features"). I see some problems in this approach:

• Standard improvements can not be made or the default branch. When casual contributors want to add a feature or fix a bug, they would have to care about the branch they are working on, and if their changes are breaking or not.
• The type of changes we accept on :develop is unclear. Bug fixes can introduce breaking changes or be a breaking change themselves (if users was relying on this bug), and so should not be in a patch release.
• Because of that, the type of changes we accept in practice on :develop are inconsistent. Whether the next release is a minor/major or a patch version, we can accept (for convenience) or reject new features and refactoring. In the first case, :develop become redundant with :6.x and the changes made on one branch are not available on the other.

These problems are not important, but they lead to a more difficult contribution and an unclear Git history.

To avoid these problems and ones previously mentioned, I have some propositions (mainly coming from GitFlow):

1. Prepare the next minor/major release on :develop.
   New features, refactoring, all others breaking changes and all fixes for bugs of the latest release are made on :develop, which constitute the _latest_ version of Foundation. Any work based on :develop can rely on all the fixes and new features previously made.
2. Prepare the next patch releases on support branches.
   Bug fixes compatible with the supported versions are merged back on the support branch (in our case support/6.x) of each compatible versions. For supported versions that are not compatible, a dedicated fix is created. Support branches can not contain any new feature or breaking change.

Here an example with Foundation versions:

...
develop (preparing 6.5)
•
•     support/6.4
|     ...
|  ⟋
•
|  ⟍  release/6.4.0 (tag: v6.4.0)
|     •
|     •
|  ⟋
•
•
•
•     support/6.3
|     •
|     |  ⟍  release/6.3.2 (tag: v6.3.2)
•     |     •
•  ⟍  |  ⟋
|  ⟍  • ← (fixes for both 6.3 and 6.4)
|     •
|     |  ⟍  release/6.3.1 (tag: v6.3.1)
|     |     •
|     |     •
|     |  ⟋
|     •
|     •
|     •
|  ⟋
•
|  ⟍  release/6.3.0 (tag: v6.3.0)
|     •
|  ⟋
•
•

SemVer

[to complete]

See also:

• A successful Git branching model

[paxperscientiam]

I don't have anything to add, @ncoden . I just want to say that I admire your dedication to Foundation. It's inspiring and I loo forward to the discussion around your ideas!

[kball]

@ncoden - I think you have well identified the challenges, and your proposed approach looks good to me. The one major concern I have is around the level of QA required to prevent regressions, as our automated testing coverage right now is... poor. That said, if we keep the number of changes in a patch version very small and do very rapid iteration releasing new patches, this may not be a huge deal.

Would be very much interested in more thoughts on this - Going to tag in a bunch of more involved folks @zurb/yetinauts @DaSchTour @pine3ree @ahebrank @gakimball @karland

[karland]

I think @ncoden has some valid points and if one wants to improve on Foundation's setup, it might be helpful to follow a defined and documented release strategy. If you are interested, here is what they do in Atom or Rust. It is claimed that Chrome follows a similar strategy.

I also agree to @kball that the testing environment could be improved. Ideally new or changed features should not be introduced without tests. I feel the testing strategy and documentation also deserve some consideration.

With respect to milestones I am undecided. It is good to see what has been identified as major TODOs. Personally, I have difficulties to see that the milestones will be reached at the pace Foundation is currently moving unless somebody is really digging in (e.g. no jQuery dependency, ES6 modularization, Webpack, CSS, ...). So, it is good to see the work and intitiave of @ncoden to push things forward...

[kball]

After discussion with the various @zurb/yetinauts we are going to move forward with this approach, starting now. We will do the 'support branch' approach starting with 6.3 (IE we will not attempt to retroactively apply this backwards).

I set up the support/6.3 branch based on the current state of develop, and am now merging v6.4 into develop to correspond with the new approach of having develop always correspond to the next minor release.

@ncoden is going to submit a PR updating CONTRIBUTING.md and the pull request template; This issue will remain open until that is true.

[ncoden]

*of having develop always correspond to the next minor or major release.

[ncoden]

@ncoden is going to submit a PR updating CONTRIBUTING.md and the pull request template; This issue will remain open until that is true.

Sorry I'm late. Working on it.

[colin-marshall]

@ncoden did #10784 close this out?

[ncoden]

@colin-marshall If you means https://github.com/zurb/foundation-sites/pull/9665 and https://github.com/zurb/foundation-sites/pull/10874, yes.