Decide & correct HOW TO EDIT

[joncison]

From @matuskalas on May 11, 2016 10:48

Correct claims about releases.

Refine info on how to edit and how to release.

Mention all info related to GitHub issues and Travis CI.

Copied from original issue: edamontology/edamontology#174

[joncison]

From @matuskalas on May 11, 2016 11:23

Rethink the token workflow.

Rethink merging. NB. that IDs have to be updated manually (EXTREMELY ERROR-PRONE) including throughout the relations!

Add: please commit and push often!

Add: write meaningful commit messages. Refer to tackled issues (but preferably without automatically closing them before the next release. If that stays the workflow)

Add best practices of dealing with GitHub issues: comments, labels, assignee, mentioning commits, merging, referencing other issues, etc...

[joncison]

From @matuskalas on May 11, 2016 12:24

Add: Double-check whether commits are pushed to the public repo.

[joncison]

From @matuskalas on May 11, 2016 12:51

And we must either:

• Forbid editting in Protégé(!!)

Or

• include an automated canonical reformatter, if possible, with every add/commit/push (See also #173. NB. that a manually launched reformatter before every add/commit would just again keep being forgotten)

OTHERWISE DIFF AND SUBSEQUENTLY ALL CHANGE TRACKING, MERGING, METRICS, etc. IS OUT OF ORDER!

[joncison]

From @matuskalas on May 11, 2016 16:25

Decide and document the workflow with closing issues and labelling them done - staged for release.
Including:

• when to label and unlabel done - staged for release?
• use done - staged for release at all or not?
• what to write in the last/closing comment? (promising a version=release? non-dereferenceable or dereferenceable URI of a new concept? ... NB. that these all can change!! And even the whole issue can be "undone" until the next release.)

[joncison]

From @matuskalas on May 12, 2016 18:48

Visual checking

Use http://webprotege.stanford.edu:

1. Have patience
2. Register
3. Log in
4. Upload your local EDAM_dev.owl
5. Click Share
6. Make Private
7. Have patience
8. Visually browse your EDAM
9. Don't edit, or at least don't download
10. Enjoy your EDAM!

[joncison]

From @matuskalas on May 14, 2016 12:15

Please ALWAYS add a label to an issue when closing it! Otherwise changelogging, reporting, and writing release notes are impossible! Please use the following:

• done - staged for release -- needed to see what is going into the next release
• duplicate -- please first note which issue this a a duplicate of
• invalid -- write why, e.g. not true that a requested concept or term is missing
• won't fix -- write why, e.g. is a bug or a missing feature, but is out of scope or granularity
• wrong project -- use https://github-issue-mover.appspot.com/ (needs to be tested!), while needs to be labelled with wrong project manually. Preferably don't copy & paste issues manually, then contributors info and parts of discussion may get lost.

When closing automatically with commit messages, please add a label manually immediately after!

After the release is done, and all release notes and statistics are written, change done - staged for release to fixed - released or partially fixed.

• This needs to be part of the release recipe.
• NB. FIRST add fixed - release or partially fixed, THEN remove done - staged for release!
• fixed - released and partially fixed are needed for seeing and reporting what has been done, and for attributing contributions!

[joncison]

From @matuskalas on May 14, 2016 12:45

When (quick-)fixed an issue, but a discussion or question or whatever is open for eventual further improvements or refactoring, label with partially fixed, done - staged for release (and optionally with discussion or question or something), and DO NOT CLOSE!

[joncison]

From @matuskalas on May 31, 2016 23:38

Use British English spelling in the main (preferred) labels, and always add American English spelling as synonyms. (Has been reported separately in #184)

[joncison]

From @veitveit on October 2, 2016 14:16

Some of the comments above have been implemented into https://github.com/edamontology/edamontologyDocs/blob/master/editors_guide.rst.
What about the rest (e.g. Visual checking and usage of Protege)?
This issue should be easy to close after getting to consensus of what will need to be documented.

[joncison]

@hmenager please move this to the right tracker (https://github.com/edamontology/edamontologyDocs)

[joncison]

From @matuskalas on October 11, 2016 18:53

With respect to the token vs. merging workflow, a suggestion:

What about if everyone editing EDAM_dev.owl (i.e. core devs and everyone who sends a pull request) has their own sequence of IDs, e.g. edamontology.org/data_mk0001...etc., that will be automatically replaced with proper IDs either before the release (freeze time), or at some intermediate points, or at every push (How to implement? Similar issue to automated reformatting, but more complicated with additional concurrency).

Until the workflow is decided, and necessary automations implemented, this issue should stay here and open. I updated the title accordingly.

[joncison]

From @matuskalas on October 11, 2016 19:28

And until we have an automation for consolidating the temporary IDs, we could follow the following points:

• If not adding new concepts and not reformatting things around (e.g. with Protégé) and not doing drastic refactoring, you don't need the token.
• Take token for exclusive QUICK changes, including manual consolidation of the temporary IDs. Then first commit EDAM_dev.owl with next_id changed from XXX to TOKEN_TAKEN_<NAME>_XXX. Everybody will immediately see that adding new concepts is blocked.
• If adding concepts, start with changing in your local file the next_id from XXX to e.g.XXX__<NAME>012, then give your next concept a temporary ID http://edamontology.org/data_<NAME>012, and then update next_id to XXX<NAME>013. Commit and push origin as is.
• Before a consolidation of temporary IDs occurs, the next_id in the common EDAM_dev.owl at GitHub will look something like e.g. XXX__ji252__hm013__vs345__mk05.
• The "manual" consolidation of temporary IDs will need a rather trivial script replacing the temporary IDs with proper ones. Thus "manual", meaning that the consolidation is launched manually, but done with help of a simple script.

What do you @joncison @hmenager @veitveit think? I'd suggest thinking about it now, and perhaps trying it after the coming release.

[joncison]

I think we'll need to revisit this when we get more contributors ... that may happen fairly soon given the ideas for thematic editors

[joncison]

This needs to be migrated across to https://github.com/edamontology/edamontologyDocs really.