Develop a dictionary release schedule and policy

[jamesrhester]

(I will put this to COMCIFS via the mailing list as well).

We should develop some sort of dictionary release policy. At the moment we commit updates to the master branch of the dictionary on Github, and no further release activity happens. The status of the release is unclear: is it official once the commit is made? It certainly has an internal version number. I suggest we develop a process. Here is a start:

1. A dictionary becomes official once it has been tagged on Github as a Github release
2. A Github release should be simultaneously reflected on the main IUCr website as the latest version of the dictionary
3. The machine-readable dictionary catalogue should be updated at the same time as (2)
4. There should be one release at least every 3 months unless a dictionary has not changed in that time.
5. A dictionary may be released sooner than every 3 months if there is an urgent need
6. Approximately one week before the official release date relevant IUCr mailing lists should be advised of the forthcoming release together with a summary of changes
7. A "release manager" is nominated for each dictionary and is responsible for managing the release process.

Thoughts?

[vaitkus]

Seems good to me. Some more technical suggestion on the dictionary development cycle are also discussed in another COMCIFS document, but none of the new proposals seem to conflict with the existing ones.

I also link the COMCIFS mailing list discussion mentioned in the original post.

One thing that should be further specified is which one of the multiple dictionary locations (GitHub, IUCr website, Zenodo, etc.) should be regarded as the original one and reflected in the dictionary URL. Currently, the GitHub raw file URL is used (e.g. https://raw.githubusercontent.com/COMCIFS/cif_core/master/cif_core.dic), but this does not look like a good long-term solution. Firstly, the dictionary URL relies on the GitHub API which might change at any moment thus breaking the links in all older dictionary releases. Secondly, the URL always points to the newest commit in the master branch and not a specific tagged version. Maybe a IUCr URL of some sorts could be used in the tagged releases?

I can open a separate issue for the discussion on URLs if you think that it has the potential to derail the main discussion.

[jamesrhester]

My idea on URLs is that we should mint a DOI for the dictionary and use the dx.doi URL for the URL in the dictionary. At first the DOIs would come from Zenodo, and if/when the IUCr journals are able to provide us with DOIs then we can switch to their service instead. The one inconvenience is that the automatic Github/Zenodo release management tools won't work because we'd need to manually insert the DOI into the newly-released dictionary before publishing.

On the bright side, the IUCr webpage could always link to the latest version simply by giving the DOI of the collection of releases, which always resolves to the latest version.

[jamesrhester]

I have started a release cycle using a tasklist in #317 . Please feel free to add things missing from the tasklist, and issues that you undertake to resolve "immediately". In the future we'll nominate a cutoff date for PRs, but for now I'd like to get a feeling for what sort of timescales we are dealing with.

Brian McMahon has raised important issues on the comcifs mailing list around the URL for the dictionary that have not been addressed. I'm hoping that this will be addressed in this process. Key issues:

1. Is the URL a landing page or the actual file?
2. Is the URL persistent?

I see this as something we can improve over time and need not stop the release.

[rowlesmr]

Should there be a development branch against which everything is added, while the main branch holds the official release? That will allow thing s to be added and potentially tested, with the knowledge that any and all of it could change at any time.

Then dev can be pushed to main every so often to add new features.

[vaitkus]

Should there be a development branch against which everything is added, while the main branch holds the official release? That will allow thing s to be added and potentially tested, with the knowledge that any and all of it could change at any time.

I am not sure if a separate development branch is needed. Currently, the main (master) branch is used for development/testing while stable official releases end up as immutable tags. One things we should eventually do is tag more often, but I think that currently dictionaries are still a bit suffering from the DDL1->DDLm growing pains.

I would actually actively discourage people from basing their work on an untagged version (i.e. any branch) given that it may change at any point. To my understanding even the main branch under the scheme that you propose would suffer from this due to syncs with the dev branch.

[jamesrhester]

I agree with @vaitkus.

As far as I can tell, the pull request branches end up being the "development" branches - so we discuss pull requests and develop on each topic (pull request) branch, and then the topic branch is merged into "main".

[rowlesmr]

I kind of agree with the above.

In addition, the readme file in the cif_core github doesn't tell you how to get the current version. There is a tagged release from 2020 in the sidebar, yet the IUCr says that the current release is 2.4.5. The current dev version is labelled as 3.2.0, but there are no other releases.

Also, I think I'm hitting on why you want a formal release framework.