This will allow us to start opening pull requests against 4.x for review.
While we work on 4.x, 3.x will still be the “recommended” branch, and we will continue to make 3.4.x releases (to fix bugs and update dependencies).
We will most likely put a “feature freeze” on 3.x, meaning there will be no more “minor” releases, only “patch” releases (following semantic versioning). So there may never be a 3.5.x branch, because all new features will target 4.x.
Some of the ongoing 3.x “patch” changes will also happen in 4.x, but some won’t (eg: bug fixes that affect both will be applied to both, but we will be updating drupal/core separately).
In the past, we minimized the overlap between 2.x and 3.x, and didn’t need to maintain separate branches/release notes. This time we might.
Our CHANGELOG.md currently has a nice chronological history, including all 2.x and 3.x releases (we adopted this practice in 2.x, so it does not include `1.x releases).
https://keepachangelog.com doesn’t provide guidance on how to manage CHANGELOG.md when maintaining two branches in parallel.
We need to decide how we want to proceed. I’d like to figure this out before we open the official 4.x branch, because it will inform our parallel development process.
Assuming we consider 4.x the “main” branch, and commit all new features and bugfixes there first, then backport appropriate changes to 3.x and tag a new 3.4.x release, do we include the 3.4.x release notes in the 4.x branch’s CHANGELOG.md? I think we should, because ideally the “main” branch’s CHANGELOG.md should contain ALL releases (IMO).
But what if we decide to release a 4.0.0-alpha1 (before the official 4.0.0 release, and therefore 3.4.x is still the “recommended”), and then we release 3.4.5 after that. Do we continue to list the releases in chronological order in CHANGELOG.md? So in other words, would the releases appear in this order?
3.4.5
4.0.0-alpha1
3.4.4
I don’t love that, because it makes it harder for someone to review changes on only the branch they care about. This is the same problem that the release lists on GitHub and Drupal.org suffer from (major version releases mixed together).
If, on the other hand, we keep them grouped by major version, then we lose the true “chronological” order of the CHANGELOG.md… for example (release dates are made up to illustrate the issue):
One idea I brought up on the call is that we could make a conscious choice NOT to release any 4.0.0-alphaX or 4.0.0-betaX releases. This would side step the issue, because as soon as we are ready to release 4.0.0 we would stop supporting 3.x, so 3.4.x releases would stop being produced, and we would start producing 4.x releases.
@paul121 made the valid point that alpha and beta releases are useful to encourage more testing.
Another idea that came up on the call was to maintain separate CHANGELOG.md files for each branch (eg: CHANGELOG-3.x.md and CHANGELOG-4.x.md). This could work, but does that mean we should also split out a CHANGELOG-2.x.md?
I think my preference would be a single CHANGELOG.md, generally.
In my non technical opinion I think listing them in chronological order like this is the way to go. It really does preserve what happened in order.
I think there are 2 relatively easy solutions to make it easier to follow a particular branch.
There could be a table of contents at the top with each branch listed separately.
3.x branch
3.4.5
3.4.4
3.4.0
4.x branch
4.0.0 alpha
The second thought is at the end of each change, list and link to the previous version. So if you need to go further back you can easily follow where to go back to.
I was about to chime in to say that this conundrum is a consequence of the practice of Changelogs as a single static file – i.e. an unfilterable form of logging.
Then @Symbioquine happens along with this expose of Github’s filterable Changelog.md contents, which certainly seems to boil away the concerns here?!
I am more often critical towards Github than I am favorable (I prefer GitLab, Gitea) but this appears to be quite a thoughtful and useful enhancement indeed.
Sadly GitLab doesn’t appear to have a comparable feature, but it’s also just text so we can use all our favorite tools to filter/manipulate it…
$ awk '/^## \[3\.2/ {p=1; print; next}; /^## \[/ {p=0}; p' CHANGELOG.md
## [3.2.4] 2024-09-18
### Changed
- [Single Dockerfile using multi-stages for production and dev image #855](https://github.com/farmOS/farmOS/pull/855)
- [Simplify recommendation for XDEBUG_CONFIG in local development environments #870](https://github.com/farmOS/farmOS/pull/870)
### Fixed
- [Update drupal/consumers to ^1.19 and fix kernel API tests](https://github.com/farmOS/farmOS/pull/857)
- [When a quantity is deleted, clean up log references to it #859](https://github.com/farmOS/farmOS/pull/859)
## [3.2.3] 2024-07-21
### Fixed
- [Issue #3454144: Fix untranslated plant_type descriptions in plant and seed asset types](https://www.drupal.org/project/farm/issues/3454144)
- [Set owner of cloned assets to current user #851](https://github.com/farmOS/farmOS/pull/851)
- [Issue #3314741: EntityFieldManager::getFieldMap() doesn't show farmOS bundle fields](https://www.drupal.org/project/farm/issues/3314741)
## [3.2.2] 2024-05-17
### Added
- [Allow columns to be selected for inclusion in CSV exports #842](https://github.com/farmOS/farmOS/pull/842)
### Changed
- [Allow multiple locations to be referenced in the planting quick form #839](https://github.com/farmOS/farmOS/pull/839)
- [Update farmOS-map to v2.3.0 #841](https://github.com/farmOS/farmOS/pull/841) to [add the ability to use custom stroke colors #201](https://github.com/farmOS/farmOS-map/issues/201) (in custom map layers)
- [Improve comment settings and edit sidebar #846](https://github.com/farmOS/farmOS/pull/846)
### Removed
- [Remove default country from farm settings form #840](https://github.com/farmOS/farmOS/pull/840)
### Fixed
- [Remove data_table from existing plan_record entity type definition #829](https://github.com/farmOS/farmOS/pull/829)
- [Use farm_people entity_reference View for exposed Owner filter in farm_asset View #835](https://github.com/farmOS/farmOS/pull/835)
- [Require asset name in bulk KML importer #836](https://github.com/farmOS/farmOS/pull/836)
- [Fix incorrect CSV headers when exporting multiple record types #842](https://github.com/farmOS/farmOS/pull/842)
## [3.2.1] 2024-04-12
### Fixed
- Patch JSON:API Schema to fix [Issue #3390505: Error: uri is not a valid type for a JSON document](https://www.drupal.org/project/jsonapi_schema/issues/3390505)
- [Fix FieldException: Attempted to create a configurable field of non-configurable field storage image during update.php #828](https://github.com/farmOS/farmOS/pull/828)
## [3.2.0] 2024-04-10
### Added
- [Issue #3352183: Comments on farmOS records](https://www.drupal.org/project/farm/issues/3352183)
- [Add a Notes filter to the logs views #825](https://github.com/farmOS/farmOS/pull/825)
- [Add file and image base fields to all taxonomy terms #807](https://github.com/farmOS/farmOS/pull/807)
- [Issue #3390486: Add an Ontology URI field to all taxonomy terms](https://www.drupal.org/project/farm/issues/3390486)
- [Add "Days of harvest" field to Plant type terms #794](https://github.com/farmOS/farmOS/pull/794)
- [Plan record views integration #818](https://github.com/farmOS/farmOS/pull/818)
- [Add min/max options to decimal fields in farm_field.factory #822](https://github.com/farmOS/farmOS/pull/822)
### Changed
- [Set plant_type fields form/view display settings via alter hook instead of config #806](https://github.com/farmOS/farmOS/pull/806)
- [Make "done" the default log status #782](https://github.com/farmOS/farmOS/pull/782)
- [Set the minimum value of maturity_days and transplant_days to 1 #794](https://github.com/farmOS/farmOS/pull/794)
- [Move transplant_days field to farm_transplant module #795](https://github.com/farmOS/farmOS/pull/795)
- [Use content form for taxonomy terms #810](https://github.com/farmOS/farmOS/pull/810)
- [Override the lab_test log timestamp label and description #774](https://github.com/farmOS/farmOS/pull/774)
- [Override the birth log asset label and description #824](https://github.com/farmOS/farmOS/pull/824)
### Fixed
- [Fix Client error when passing asset parameter to forms #814](https://github.com/farmOS/farmOS/pull/814)
- [Update patch for Issue #3397275 to fix boolean field JSON Schema #819](https://github.com/farmOS/farmOS/pull/819)
- [Do not trim whitespace from quantity field item content #820](https://github.com/farmOS/farmOS/pull/820)
- [Do not install base modules when --existing-config is used #821](https://github.com/farmOS/farmOS/pull/821)
### Removed
- [Remove CSV export display from farm_plan View #809](https://github.com/farmOS/farmOS/pull/809)
It seems like most the complexity around this decision is directly related to this, trying to keep ALL releases/change records in the main branch. I understand the goal and idealism around having a single source of truth but I guess I’d like to challenge how important that is and suggest we KISS
One simple solution I liked from the call that I don’t see mentioned here (I think @Symbioquine idea) was to include a link in the 4.x changelog that points to the changelog in 3.x branch with some text like “See the 3.x branch for later 3.x changes”.
This approach could help with this, too. When starting 4.x we could remove all the historical 3.x change records and replace with a very clear link to the changelog in the 3.x branch. This would make it more clear where to go to find only the 4.x or 3.x change records. It would also remove any ambiguity and inconsistencies that might come from the alternate approach of maintaining the 3.x change records in both branches.
If we are really concerned with having a single place with all change records we could consider adding a page to our website that aggregates change records from the CHANGELOG.md in each version branch. Such a site could have features to sort the change records chronologically or group by major version. It could get as complex as we want
I also wonder: is it slightly incorrect to include any change records in the 4.x branch for things that were never actually committed to 4.x?
