euroargodev / euroargodev/software_guidelines

Issues or bugs are fully documented

Open
#15 1 comment 0 reactions 0 assignees View on GitHub
auto-checked-guideline guideline
Dominant language
Python
Stars
0
Forks
0
PR merge metrics
No merged PRs in 30d

Description

If your codebase is hosted on a git-based web-platform (eg: Github, Gitlab), issues and bugs are easily managed through the "issues" tabs, see guideline #27 .

**It is a good practice for issues and bugs to be as descriptive as possible.**

This will allow maintainers and other users to clearly identify the issue in order to address it or to identify another occurence.

**Issue content**:
When posting an issue, users should be invited to provide, at least:
- a clear description of the issue, including which Argo component is related (eg: mission, files, vocabulary, etc...)
- a reproducible example (eg: a code snippet for the community to reproduce the issue).

These information can be completed with: images, environment definitions, optional settings, etc...

**Labels**:
It is also a good practice to use labels to appropriately tag new issues: this makes them easily searchable, sortable.

[Labels are fully configurable](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels) on the repository and organisation levels. On the euroargodev platform, labels referring to Argo missions or components are already available by default and will appear on any repositories.

**Templates**:
On Github it also possible to [create templates for issues](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository), so that creating an issue can be done by indicating to users the expected information.

Example taken from here:
https://raw.githubusercontent.com/euroargodev/argopy/refs/heads/master/.github/ISSUE_TEMPLATE/bug_report.md

```markdown
---
name: Bug report / Feature request
about: 'Post a problem or idea'
title: ''
labels: ''
assignees: ''

---

#### MCVE Code Sample

``python
# Your code here
``

#### Expected Output

#### Problem Description

#### Versions

```

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.