This repo is for logging and managing issues in the NMDC repo. To log an issue go here.
Decisions are tracked as ADRs in the decisions directory.
Tools related to managing issues are located in the tools directory.
Tip: There is a notion that things are generally read more times/by more people, than they are written. Spending extra time writing something clearly up front can save readers energy each time they read it.
Note: Members of the
microbiomedataorg that cannot see a list of org-level labels will not be able to follow this guideline.
Before creating a label at the repo level, check whether a similar label already exists at the org level. If one does, create a label having the same name and description as that org-level label. That can make it easier for team members that work on multiple repos to leverage their existing knowledge.
When creating a label, include a description that you think will make sense to the other people that use that repository. That can make it more likely that team members (including your future self) share a common interpretation of the label.
For example, the label big could be interpreted as "Going to take a lot of time", "Involves a lot of data", "Involves something that happens to be abbreviated as B.I.G., such as the BioInformatics Group", etc. Given those potential interpretations, a disambiguating description could be "Impacts the bioinformatics group".
When copy/pasting a code snippet into the issue description, wrap it in a code fence. That can make it easier for people to read.
| Raw code :tired_face: | Monospaced code :relieved: | Colored monospaced code :heart_eyes: |
| { "id": "string", "capability_ids": [] } | ``` { "id": "string", "capability_ids": [] } ``` | ```json { "id": "string", "capability_ids": [] } ``` |
You can achieve the rightmost version by wrapping the raw code with this (without the + signs):
+ ```json
{
"id": "string",
"capability_ids": []
}
+ ```Alternatives to json include py (short for Python), Makefile, yaml, and all the other language identifiers listed here.
Sometimes, team members want to create an issue that encapsulates multiple sub-issues. Some team members refer to such an issue as an "umbrella issue" or "meta issue."
When creating such an issue, please add the meta-issue label to it.
Note: The
meta-issuelabel does not exist at the org level yet.
Here are some examples of meta issues: