search

OCHA-DAP / hdx-signals

HDX Signals
https://un-ocha-centre-for-humanitarian.gitbook.io/hdx-signals/
GNU General Public License v3.0
6 stars 0 forks source link

Finalize semantic versioning approach #179

Closed caldwellst closed 5 months ago

caldwellst commented 5 months ago

We should finalise the approach for versioning, document it in CONTRIBUTING.md, and follow it. Here are some snippets of the discussion on Slack!

What we need

@hannahker:

IMO:

  • I think it's important that for each signal sent, we know which version of the codebase it was generated from.
  • We also want to be able to communicate/publicize important changes that users would care about.
  • We want to have a developer workflow that's as straightforward as possible

Dev branch

I'm also pretty against a dev branch, since it'll add lots of complexity and I don't really see a reason why we wouldn't want to immediately release changes to the main branch

@caldwellst

And a dev branch keeps popping up as a potential solution to store changes until we have a release ready solution. However, the issue I still see is that a lot of the changes we are pulling in today we want to go straight into the monitoring, because they are hotfixes or changes critical to the runs. So those wouldn’t go into dev.

And other changes like changing the name of the env variables could sit in something like dev, but the issue is that we wanted to merge it to make all our PRs cleaner and in the new setup. And having that in dev would probably only serve to make it MORE complex for various hotfixes into main with the old setup not aligning with dev.

@hannahker

I'm also pretty against a dev branch, since it'll add lots of complexity and I don't really see a reason why we wouldn't want to immediately release changes to the main branch

Release tags

@hannahker

Like, what if we issued Releases, and were able to configure the GitHub actions to always run against the latest Release tag instead of main. It might be a bit ugly to configure and is kindaa similar to using a dev branch, but would allow us always push to the same main branch and pretty quickly and simply do releases

@caldwellst

I think the release tags don’t really solve anything because it’s just added complexity that means changes aren’t immediately reflected in emails while complicating dev workflow and management to ensure changes we want reflected in runs have been reflected.

Semantic versioning

@caldwellst

So there are a couple of things I was thinking about:

  1. Not iterating the semantic version, just adding notes in changes if those changes are small. So basically having a # 0.1.1 section in the CHANGES.md but only adding to that for changes that are not publicly facing or critical. So the subsections could potentially be dated to reflect when those additions were made?
  2. Kinda related, but we could use 0.1.1.1 to reflect those smaller changes within, so having a 4th level of versioning beyond patch that is for patches that are not affecting the public. Basically still as complex to version though, but might better let us reflect minor adjustments especially in this current period.
caldwellst commented 5 months ago

So, been thinking more on this, and what about the following proposal?

  1. We use semantic versioning in its most standard format, 1.1.1. But we only increment the semantic version for changes that impact mails. So documentation changes, improvements to linting, wouldn't be reflected.
  2. We use GitHub release tags on any of these. So we also have it clear on GitHub when releases have happened that impact mailings.
  3. However, we don't have to adjust code to use only releases for runs. Since any changes after a release won't affect runs, by how we approach versioning, we just always use the latest main for all runs, keeping dev workflows simple.

Thoughts @hannahker @zackarno?

hannahker commented 5 months ago

Thinking about this more... IMO only documenting and versioning against a subset of changes could be dangerous, or at least confusing. Firstly because I could imagine it getting ambiguous whether or not a certain change impacts the emails or not. Secondly, I worry it could be confusing to potential contributors (or even ourselves) when a changelog/versions don't reflect the full scope of changes in the repo.

In light of this, I would advocate for going all or nothing with versioning. We either decide on the contribution/release structure to version against every change (potentially requiring some kind of pre-release staging), or we drop the versioning altogether. Going for the former seems more appropriate, but my thinking on how exactly that should be implemented is still incomplete...

caldwellst commented 5 months ago

What you're saying makes sense. I think what we do is simply require that the version is always incremented in every PR. Shouldn't be hard to have a check on merging PRs to main that requires the .signals_version file to be changed. I don't know about the pre-release staging, because all I've ever really seen for that is something like a dev branch which doesn't seem we want.

Shall we just add a fourth level to versioning 1.1.1.X that is simply there when we don't think changes reflect the need for a patch. For instance, changes to documentation in Gitbook, improvement in documenting functions, that sort of thing. And if we aren't super consistent there, I don't think we need to be that worried as long as we have incrementation with every change and that is reflected in the dataset.

caldwellst commented 5 months ago

To make it more concrete, have tried to reflect this in the complex boundaries PR (also adding a few other changes that we haven't logged from other PRs):

https://github.com/OCHA-DAP/hdx-signals/pull/178

# Changes

## 0.1.2.0 (20 June 2024)

### Maps
- New country boundaries spatial data used for locations that do not
have COD boundaries, replacing the simplified boundaries used previously

### System
- ISO3 codes added to the location boundary GeoJSON files
- Added additional level to semantic versioning, `0.0.0.X`, to be used
for patch changes that do not impact the signals, such as changes to documentation
or changes like the above (adding ISO3 codes to internal files for our convenience)
- Pass `HS_HDX_BEARER` env var to `update_assets.yaml` action
hannahker commented 5 months ago

Yeah, I think that's fair! Looking at some GitHub actions which might help us automate things further and address the problem of conflicting version increments across multiple PRs open at the same time:

I can play around with some of them if you also think they'll help

caldwellst commented 5 months ago

Yeah that would be great! Do you think the above makes sense for now and I can merge that PR?

hannahker commented 5 months ago

Yes!