Write clear release recipe

[joncison]

From @matuskalas on July 8, 2017 19:37

Quick notes right now, a proper recipe TODO:

1. Release candidate

Iterate each point until success:

• Make sure Travis CI builds successfully and date is the last save date of EDAM_dev.owl in GMT.
• Update the live version at WebProtégé, check whether alright.
• Double-check all commits to master (diffs) since the previous release {requires automated EDAM reformatter if editted EDAM graphically}
• Upload EDAM_dev.owl to NCBO as a new version {one can mark release candidate by having upload one date earlier that the expected future release date if that's the case; keep status 'production'; do other things while waiting for parsing; if not parsed in 30-60 minutes, contact BioPortal but mind ~8hr diff}
• Upload EDAM_dev.owl to edamontology.org and point /EDAM to it. OLS will pick it up at some point during the afternoon (1.19 was 13:05 GMT)
• After parsed, check at BioPortal whether alright.
• After parsed, download CSV from BioPortal, beautify accordingly in Excel or similar, and check thoroughly whether alright.
• Check OLS that ok (hierarchy, relations, synonyms, defs & comments, subsets, additional attributes)

Excel:

1. Change decimal and thousands separators to nonsense chars (e.g. ¼ and ½). {Q: Can be hacked into a macro incl. this?}
2. Open CSV from BioPortal
3. Sort rows by "Class ID"
4. Save as Text (not Mac and not DOS) and CSV (not Mac and not DOS), rename .txt to .tsv
5. Extend columns to see content, review|validate (visually and semi-automatedly)

2. Release online

• In the meantime, or whenever waiting, enhance changelog and list all tackled issues accordingly.

3. Release (i.e. freeze and tag) on GitHub and Zenodo

4. Notify Hans to update bio.tools and give green light back

5. Update DOI mentions and announce

• All checks and code review
• Change version from _dev to w/o 'dev', update date, save & commit
• Upload to NCBO & edamontology.org (before release!!!)
• After 30min download CSV from NCBO; set Excel separators to nonsense; open in Excel; save as CSV & TSV (not Mac and not DOS!) to /releases
• Review again (in Excel and e.g. Notepad++ and/or XMLSpy), repeat previous in case of a major fault
• Copy new version to /releases/EDAM.owl|csv|tsv, commit
• Generate Bubastis and fill into changelog.md
• Review all issues closed or labelled done|partially|duplicate|won't|wrong|etc., fill numbers into changelog.md accordingly, amend changelog notes
• Release on GitHub: copy the corresponding part of changelog.md into the release notes, add _x.y.owl|csv|tsv files and changelog.md (must be AFTER all the previous steps!!! In particular because of Zenodo (DOIs)!)
• Change version of _dev.owl to x.y+1_dev, update date, save & commit
• Close 'Done - staged for release' issues and relabel them to 'Fixed, released'
• Update page.html in GitHub and upload to edamontology.org
• Update the generated Zenodo record with ORCIDs, licence, OWL link, grant, etc. (see previous record) Tip: Paste the release text from GitHub (while showing it, not editing), and all links will be in!
• Announce on mailing lists, ResearchGate, and Twitter, tweet particularly interesting news or views separately (N.B. that neither @EBIOLS nor @bioontology URLs provide any pictures for tweets)
  • RG:
    1. Textual update with formatted release notes
    2. Added code (.owl, Add authors immediately!! Then edit after added (because of RG bug) desc, DOI, license, etc. Then add to the EDAM project)
    3. A textual update of Bio.Tools that/after EDAM updated to the given version (with release notes again?)
  • Twitter:

Copied from original issue: edamontology/edamontology#294

[joncison]

Fantastic - we need an update to:
http://edamontologydocs.readthedocs.io/en/latest/editors_guide.html#creating-a-new-official-edam-release

https://github.com/edamontology/edamontologyDocs/blob/master/editors_guide.rst

[joncison]

From @matuskalas on July 10, 2017 8:19

Will do when I get to it. Perhaps the best together with the next release 1.19

[joncison]

The guidelines in readthedocs would benefit from a general spring clean (making them easier to follow, more concise, clearer ...)

[joncison]

From @hmenager on July 25, 2017 14:51

additional thoughts from meeting with @matuskalas :

• NCBO and edamontology.org uploads need more detailed documentation and to be accessible by all core devs.
• for tabular formats, is there a way to generate them locally without NCBO? maybe get in touch with them to know if there is a local alternative.
• code review: yeah, we need more of that ;) - but having a checklist of what needs checking is probably going to not help.
• commits: we need these to be diff-able, to enable review. possibilities include tooling to correct Protégé serialization, alternative formats (text-based formats?), other?
• bubastis: ok, but needs automation

[joncison]

From @matuskalas on September 13, 2017 9:55

Adding:

• Use EDAMetrics to generate vital statistics e.g. # of concepts and synonyms etc.

[joncison]

From @matuskalas on September 13, 2017 9:58

And the most correct way would probably be:

• Create/tag the OWL file as 'release candidate' first, do uploads and various code reviews with that one, and only afterwards create a stable release (with re-uploading to edamontology.org and NCBO).

[matuskalas]

Status update: This has been (and is) crystallising, being refined and tested with every EDAM release. A more stable version (to include in the docs) is to come soon(-ish)...