Changing Organisation Name to hubverse

[annakrystalli]

This announcement contains planning details of tasks surrounding the change of our organisation name to hubverse.

There are two areas where there are org name change has implications:

1. Schema IDs contain the URL of config schema in our schema repository. This affects both the schema themselves as well as any config files in hubs or test data.
2. API calls to repository organisations in GitHub

Actions required by different stakeholders/resource type

Hubverse Package devs

Perform all changes on hubDevs first!

• Create to-hubverse branch.
• Find and replace any instance of the Infectious-Disease-Modeling-Hubs organisation name with the new hubverse name.
• Must change the organisation name in the schema_version of each tasks.json & admin.json config file in any test files and upgrade to schema latest version.

Additional tasks

• Configure docs to use hubStyle (use_hubdev_pkgdown())
• Update all repos with Community level documents (use_hubdev_community())
• Add standard hubverse actions (use_hubdev_pkg_actions())
• Add standard footer to README (where necessary)
• Set up Netlify site for PR docs previews (need Netlify credentials)
• Bump version and add to NEWS

Schema repo:

Am a bit unsure what to do about the schema repo as nothing will change in the schema apart from the organisation name in each schema's ID.

Q: Should we change org name across the repository or only in new version folder?

I feel if we were doing everything robustly we would only change org name in the new version folder. However, if we were doing things robustly we would actually look to work back-compatibility into the framework and avoid disruption which is not the approach we are taking. It also means that all hubs will need to upgrade both org name AND schema version to correctly point to a schema file under the new organisations name. This means they will necessarily have to upgrade to at least v3.0.0, which means changes to the repository property in admin.json will also be required.

If we change the org name throughout the repo in the new release(i.e. in the schema ID of previous versions of the schema also), hub will only need to change the org name in their current schema and don't need to change the version they are using.

Q: What should the version number be? v3.1.0? or does this require a full v4.0.0 version upgrade?

• Create new version?
• If new version created, create new release.

Hub Administrators / Example Hub maintainers

• Create to-hubverse branch.
• Change the organisation name in the schema_version of each tasks.json & admin.json config file

hubDocs

• Change the organisation name in the schema_version of each tasks.json & admin.json config file
• If new schema version created, upgrade schema version number in conf.py
• Create new hubDocs release.

Users

• Update to new version of any packages used.

Timeline

Key Dates

Community notification Date: June 3rd 2024

Down for maintenance Date: June 17th 2024 (Provisional)

---

Community notification.

An notification must be sent out to the community advising of the breaking changes and notifying hub administrators and hubverse package users to follow upgrade instructions after organisation name change.

Happy to support Hub admins by opening PRs for them, ready to be merge when the organisation name changes if they request it.

The notification should go out atleast 1 week prior to change date.

to-hubverse PRs

Prior to making the organisation name change, PRs must be openned in each repository and the appropriate changes made, ready to be merged in on the change date.

ISSUE TEMPLATES will be created for each repository type to ensure all required actions have been performed.

Change Day: Down for maintenance

It is best to carve out a day for the name change when the framework will be effectively considered down for maintenance.

This is because it will be impossible to test (unless we actually develop back-compatibility) whether the changes in the packages have broken anything as the tests on the PRs will always fail prior to org name change.

Only after the change can we diagnose whether there are bugs that need mending so change day should be scheduled for identiying and fixing such bugs.

The best day therefore for changing the org name is a day when we know submissions to known hubs is limited.

---

Package versioning

I have noticed we are stuck on devel versions on all our packages. This is probably justified still for some but it's an opportunity to move towards more production versions.

For example, I feel hubValidations is ready to move to version 0.0.1

[nickreich]

@annakrystalli a few questions about this item as we move towards announcing this for mid-June...

1. should we add "community notification date" and "down for maintenance date" dates to the above content? Right now they are blank.
2. Are the action items under "Hubs/test-hubs" the tasks that a person who is administering a hub would need to do to avoid hiccups?

[annakrystalli]

1. We should. They are blank because we've not set them yet. Have you got specific dates in mind?
2. Yes! I've updated the header to be clearer. A more elaborate descritption of the tasks will likely be needed in actual email notification.

[nickreich]

For community notification date, that should just be the date I send out this email - maybe Weds May 29?
For the "down for maintenance date" maybe sometime in the week of June 17? I have an email out to CA DPH asking about this.

When you say "a more elaborate description of the tasks will likely be needed in actual email" that sounds like more work in the short term. i was imagining sending out basically the initial post above as an announcement with follow-up closer to the time with more specifics if needed. does this sound like an ok approach?

[annakrystalli]

There's a couple of things I'm a little unsure of now I've revisited that I'd like to investigate and I'd like to add a little more detail to some of the items so can we schedule the communication for Monday June 3rd?

And yes a tentative date of Monday 17th June as change over date should work fine.

We can ask for feedback on the day of the week at the community meeting too and confirm final date afterwards?

[nickreich]

sounds good to me

[annakrystalli]

@bsweger I would be really interested to hear your thoughts on the questions above about what to do in the schema repo, particularly the IDs in schema files of previous versions?

[bsweger]

Chiming in that GitHub org name is a key component of how the cloud sync action requests access to S3. So we'll also need to update the hubverse-infrastructure repo: https://github.com/Infectious-Disease-Modeling-Hubs/hubverse-infrastructure/blob/eb8070abe606697c572d872d7378e178732275d0/src/hubverse_infrastructure/hubs/hubs.yaml#L6

Not critical, since the "hub" in question is my internal cloud testing hub, but still worth remembering.

There are two open issues that would involve using the same AWS authorization technique (i.e., would require an update once the org name changes). I noted on those that we'll hold work until the name change is complete.

• Update example-complex-forecast-hub for end-to-end cloud syncing (including parquet conversion) example-complex-forecast-hub#20
• Create AWS permissions required to deploy the model-output transform lambda from GitHub Actions hubverse-infrastructure#39

[bsweger]

@bsweger I would be really interested to hear your thoughts on the questions above about what to do in the schema repo, particularly the IDs in schema files of previous versions?

Thanks for laying this out in such detail--you're so good at making planning these switches!

Re: the schema id...my read of this page leads me to think that the old links will redirect.

It's not a definitive or thorough test, but I renamed a personal organization and confirmed that a link to the a repo's file redirected.

So we might be able to leave the IDs alone in previous schema versions?

[annakrystalli]

Announcing Important upcoming updates to the hubverse

In the week starting 17th June 2024, we'll be rolling out two important changes that have been in the works for some time now:

1. Release of v3.0.0 schema and updated versions of packages to support more formal handling of sample output types.
2. Changing the GitHub organisation name from Infectious-Disease-Modeling-Hubs to hubverse.

Timeline

Monday 17th June - Organisation Name change to hubverse

Wednesday 19th June - Release of v3.0.0 schema and new versions of packages.

If you are subscribed to our mailing list you will receive an email reminder the day before each change.

Details

More details on the new sample output type specification can now be found in our hubDocs.

The new schema also introduces a number of changes/new features:

• The repository_url and repository_host properties in admin.json have been deprecated in favour of a single repository object with separate host, owner and name properties.
• The optional hub_models property in admin.json has been removed as it's schema could create conflicts with the model_abbr and team_abbr schema specification in the hub administered model-metadata-schema.json.

• Additional properties are now allowed at the round item property level in tasks.json. This was at the request of hubs who wished to be able to store additional metadata at the round level. Note that the strictness of not allowing additional properties meant that misplaced objects in the config would result in a config validation error previously. This is not the case anymore at the round item level, so do take care with the objects you place in the round property of your config.

Implications for Hub administrators

None of these changes should affect the normal functioning of hubs. The vast majority of changes to packages are back-compatible and if hubs are not interested in collecting sample data, there is no need to upgrade to the v3.0.0 schema.

You do need to upgrade to v3.0.0 schema if you:

1. wish to collect or prepare your hub for collecting sample output types.
2. wish to configure your hub for cloud mirroring using the new repository object in admin.json.
3. wish to store additional metadata at the round level in tasks.json.

With respect to the organisation name change, URL re-directing means that the change should not affect functionality of current versions of packages. At some point soon after the name change, however, hub admins would be advised to perform a Find and Replace and replace the old name (Infectious-Disease-Modeling-Hubs) with the new org name (hubverse) throughout their hubs. Also the hub remotes will need to be changed.

Admin Task List

Must be performed after organisation name change

• Find and replace Infectious-Disease-Modeling-Hubs with the new org name hubverse (How to do this in Rstudio and VS Code.)

If upgrading to v3.0.0 schema

• Change version in the schema_id property in admin.json and tasks.json to v3.0.0.
• In admin.json, change repository_url and repository_host to new repository object.
• In admin.json, remove hub_models object. If you need to store such information, consider encoding it as part of model metadata.
• Install newest versions of any packages used.

Use newest version of hubAdmin::validate_hub_config() to ensure your changes to the schema are valid.

Test driving new functionality

The best way to test drive new features would be to use the v3.0.0 schema version PR that is queued up and install development versions of packages from development PRs/branches.

• v3.0.0. schema PR: add v3.0.0 schema with initial sample schema schemas#72
• hubAdmin PR (Reviewed): Support v3.0.0 schema sample specification hubAdmin#19
  You could use hubAdmin::validate_hub_config(hub_path = hub_path, branch = "br-v3.0.0", schema_version = "latest") to check that your hub will pass v3.0.0 schema validation.
• hubData PR (somewhat stable, my change): Support v3.0.0 schema sample specification hubData#31
• hubValidations PR: Feature/ Handle V3 sample specification hubValidations#82
• hubUtils PR: Enhancement/v3 utils hubUtils#148

You can use the ref argument to install from a specific branch of a remote, e.g.

remotes::install_github("Infectious-Disease-Modeling-Hubs/hubAdmin", ref = "feature/sample-support")
remotes::install_github("Infectious-Disease-Modeling-Hubs/hubData", ref = "feature/handle-samples")
remotes::install_github("Infectious-Disease-Modeling-Hubs/hubValidations", ref = "feature/handle-samples")
remotes::install_github("Infectious-Disease-Modeling-Hubs/hubUtils", ref = "enhancement/v3-utils")

Note about test driving hubValidations

If you'd like to test out validating v3 configured sample model output files, you'll need to use

validate_submission(
  hub_path, file_path, ...
  skip_check_config = TRUE
)

otherwise you will get an error about a non valid config version (as technically v3 is not available yet on the main branch).

[zkamvar]

Can this discussion be closed since the transition has already happened?