[RELEASE ISSUE]: Checklist for next release of cif_core

[jamesrhester]

This is a first attempt at a release checklist. We do have some things unresolved, but we'll try and deal with those as they arise. I can be release manager this time as we iron out the problems, hopefully we can rotate around.

• Release manager appointed
• _dictionary_audit.revision comments summarised
• Release branch created
• Next version placeholder created in dictionary_audit section in master branch
• Plain text summary of changes created (ideally automatic Github changeset comments)
• cif_core mailing list advised
• ccp4 mailing list advised
• All comments/issues arising during review period addressed (add to list below)
• Final DOI and URL edited into file (IUCr Chester office to advise of DOI)
• Github release tagged
• Zenodo/IUCr updated with released file

Outstanding pull requests/ issues that should be resolved before releasing. Only the very easy ones go here, e.g. 'janitorial'. Please check any issues you have raised and see if they could be resolved easily or have already been resolved.

• ddl.dic: specify that the version content type follows the syntax of SemVer 2.0  #312
• Move around cell 2 #358
• cif_core: _publ_author.name data item is insufficient as a unique key to the PUBL_AUTHOR category #103
• Improve DICTIONARY_AUDIT summaries before release. #361

[jamesrhester]

Release manager is @jamesrhester this time.

[vaitkus]

One question regarding the summarisation of _dictionary_audit.revision comments. Given that the last properly tagged version of CIF_CORE was 3.0.13, should all other versions (3.0.14, 3.1.0 and 3.2.0) be combined into a single new version 3.2.0 before release?

[jamesrhester]

What I planned to do is summarise the comments within each _dictionary_audit.revision for those three versions, without actually merging them into a single version. The plain text summary would include changes from all of those three versions.

My thinking is that the dictionary audit information doesn't have to have details of all bug fixes, minor typo corrections and so on, these can just be described as "bug and typo fixes". The nature of each change will be available in the git history. More important to keep are things like new categories being added.

[jamesrhester]

I have created an initial set of release notes in the wiki here. Please look over them and add anything you think is missing, bearing in mind that we don't want them to be so long that we lose the attention of busy software authors. @rowlesmr would you mind writing up the section on elemental composition? You could include a link to the example contained in the file.

[rowlesmr]

I've added some words and links.

[jamesrhester]

Excellent!

[jamesrhester]

I've confirmed with the IUCr Chester office that they will create a DOI for us using CrossRef, and the form of the DOI will be known ahead of time so that we can edit it in. It will also refer to the actual file, rather than a landing page.

[publcif]

I've been asked today "Why not distribute a single dictionary file?" - i.e. expanded version including imports. Any thoughts on this?

[jamesrhester]

Well the original thinking was that having imported files (templ_enum.cif and templ_attr.cif) removes repetitive boilerplate and long data tables from the dictionary. Also, other dictionaries use these files as well so it makes sense for them to be separate entities. Finally, as separate entities it is easy to update them without needing to touch the main dictionary. That latter may not be as much of a consideration now we have a smooth workflow for dictionary updates.

So we would end up with the source repository containing the separate files, and the IUCr distribution point containing the combined files? I guess that could work, as those wishing to just read the dictionaries in whatever form do not need to fiddle with auxiliary files. Sort of like a compiled version of software.

[vaitkus]

Would this also be extended to cases where dictionaries import other dictionaries?

[jamesrhester]

Would this also be extended to cases where dictionaries import other dictionaries?

That would definitely be impractical and repetitive. mode = Contents only.

[jamesrhester]

I've now placed the release files on Github and can say we have finally finished the 3.2.0 release.

[vaitkus]

Thank you for the work!