iscsc / templates

A collection of templates for the github repositories of the iSCSC.

templates

A collection of templates for the github repositories of the iSCSC.

templates's Issues

Write templates for issues and feature requests.

Before opening a branch and a PR to implement a feature, or just let the contributors to the repo know the problems, one should open a feature request or an issue respectively.

To guide the user in writing concise, complete and easy to understand issues or feature requests, a template can be very helpful.

Ideas of templates:
A pretty safe way to start is to look at the templates from github itself. The following have been slightly modified.
.github/ISSUE_TEMPLATE/bug_report.md

---
name: Bug report
about: Create a report to help us improve
title: "[BUG]"
labels: bug
assignees: ''

---

**To Reproduce**
Steps to reproduce the behavior.

**Expected behavior**
A clear and concise description of what you expected to happen.

**What actually happenned**
A clear and concise description of what the bug is.

**Additional context**
Add any other context about the problem here (screeshots if relevant, log file if existing, ...).

.github/ISSUE_TEMPLATE/feature_request.md

---
name: Feature request
about: Suggest an idea for this project
title: "[FEATURE]"
labels: enhancement
assignees: ''

---

**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

**Describe the solution you'd like**
A clear and concise description of what you want to happen.

**Describe alternatives you've considered**
A clear and concise description of any alternative solutions or features you've considered.

**Additional context**
Add any other context or screenshots about the feature request here.

The discussion is of course open to decide toward what templates to orient the resulting PR! 😋

Write a template for commit messages.

Once an issue has been opened, its topic discussed and the development of the feature or the bug fix accepted, a branch should be created.

Motivations for the template:
A great proportion of what will be seen from the outside of the branch will be the commit list. These have to be nice to read, concise and complete enough to give insights on the choices made by the developer.
A great way to encourage the authors of git commits to write "good" commit is to use a git commit template.

Disclaimer:
The definition of what a "good" git commit is is probably ill defined and is out of the scope of that issue. The idea of such a template, that could be adapted from project to project, is to allow the developers of the same project to write consistent git commits throughout the git worktree, not to impose a single, narrow view of what a commit should be.

A first idea:
I found a pretty nice template here, but it has to be adapted of course!
Since the beginning of my internship this year, I have been using the following template, which has the benefit of being super small for what it's doing.

# ----------------------------------------------------------
# Header - (type): Brief description
# ----------------------------------------------------------
#   * feat         A new feature
#   * fix          A bug fix
#   * docs         Changes to documentation only
#   * style        Style/format changes (whitespace, etc.)
#   * refactor     Changes not related to a bug or feature
#   * perf         Changes that affects performance
#   * test         Changes that add/modify/correct tests
#   * build        Changes to build system (configs, etc.)
#   * ci           Changes to CI pipeline/workflow
# ----------------------------------------------------------


# ----------------------------------------------------------
# Body - More detailed description, if necessary
# ----------------------------------------------------------
#   * Motivation behind changes, more detail into how
# functionality might be affected, etc.
# ----------------------------------------------------------


# ----------------------------------------------------------
# Footer - Associated issues, PRs, etc.
# ----------------------------------------------------------
#   * Ex: Resolves Issue #207, see PR #15, etc.
# ----------------------------------------------------------

Notes:
A tutorial on how to install the template locally will be needed, e.g. in the README.
Note that git commit templates can be defined locally, for a single repo. There is no need to force a given template on other projects.

Write templates for a CI pipeline in GitHub.

This is mostly for the future, but, once the issue has been accepted, the feature developed and the PR opened, a CI pipeline could be a great way to ensure the quality of the code that has been requested to be merged to the code base.

First ideas:
The easiest way to get started is probably to use GitHub Actions. An extensive documentation about GitHub Actions can be found here.
According to the doc, this issue will be a great opportunity to create a first draft of the .github/worklows directory and experiment with existing GitHub Actions.