Skip to content

Refactor the CONTIBUTING.md docs #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Grillo-0 wants to merge 10 commits into
base: develop
Choose a base branch
from
Open

Refactor the CONTIBUTING.md docs #32

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
7b30204
docs/CONTRIBUTING.md: Use the more usual heading convention
Grillo-0 Jan 27, 2025
8288e83
docs/CONTRIBUTING.md: Remove indentation
Grillo-0 Jan 27, 2025
4092754
docs/CONTRIBUTING.md: Fix documentation list
Grillo-0 Jan 27, 2025
59c49fd
docs/CONTRIBUTING.md: Remove branch naming rule
Grillo-0 Jan 27, 2025
74c4374
docs/CONTRIBUTING.md: Change commit message guidelines
Grillo-0 Jan 27, 2025
44ee32b
docs/CONTRIBUTING.md: Remove obligatory issue creation
Grillo-0 Jan 30, 2025
03e3b2f
docs/CONTRIBUTING.md: Remove PR bypassing rule
Grillo-0 Jan 30, 2025
384bbc1
docs/CONTRIBUTING.md: Improve the PR merging section
Grillo-0 Jan 30, 2025
837d79f
docs/CONTRIBUTING.md: Set references as links
Grillo-0 Jan 30, 2025
fbdface
docs/CONTRIBUTING.md: Add a link to the build steps in the README.md
Grillo-0 Jan 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
254 changes: 91 additions & 163 deletions docs/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,221 +1,149 @@
# Contributing to Vinum

Contributing to Vinum
==============================

Vinum is open source and you are welcome and encouraged to contribute.
Vinum is open source and you are welcome and encouraged to contribute.

These are a few guidelines.
These are a few guidelines.

Contribution workflow
------------------------------
## Contribution workflow

The official Vinum repository is at https://github.com/monacofj/Vinum

To start contributing, make sure you've read the essential documentation
thoroughly:
The official Vinum repository is at https://github.com/vinumdoc/vinum

- `docs/vinum.md
- `docs/CONTRIBUTING.md`
-- docs/CODE_OF_CONDUCT.md
To start contributing, make sure you've read the essential documentation
thoroughly:

Then, go through the following steps.
- [vinum.md](/docs/vinum.md)
- [CONTRIBUTING.md](/docs/CONTRIBUTING.md])
- [CODE_OF_CONDUCT.md](/docs/CODE_OF_CONDUCT.md)

1. Either pick an issue that you want to work on, or create a new one describing
the problem or suggestion that you want to be addressed.

3. If you want to contribute a solution for that issue:
1. Fork the project
1. Create a local branch for the issue.
1. Edit the relevant files in the branch
1. Add tests if necessary
1. Build and test following the instruction on the [README.md](/README.md)
1. Push your branch into your repository
1. Got to github and make it into a pull/merge request
1. Go have a cup of wine, as you’ve earned it

* fork the project
* create a local branch for the issue (see branch naming below).
* edit the relevant files in the branch
* run `meson compile --ninja-args=clang-format` to format your code changes
* push your branch into your repository
* got to github and make it into a pull/merge request
## Project standards

Do not submit a PR/MR that is not related to an open issue.
To keep things consistent, when applicable, we aim at some some standards.

If you're going to work in your own issue, it's a good idea to request for
comments from the project maintainers before staring to code.
- [REUSE specification vr. 3][reuse]

5. Go have a cup of wine, as you’ve earned it.
- [GitFlow branching strategy][git-flow]

Project standards
------------------------------
- [Semantic versioning 2.0.0][semver]

To keep things consistent, when applicable, we aim at some some standards.
## Code convention

- REUSE specification vr. 3 [1]

- GitFlow branching strategy [2]
Oh, that.

- Semantic versioning 2.0.0 [3]
Code convention always tend to be a sensitive topic among programmers as it
calls forth personal convictions and the weight of beloved traditions. As often,
preferences vary largely. With that, we humbly as you to be indulgent about the
choices made in this project.

Code convention
------------------------------
* Symbol names, comments, file names etc. always in English.

Oh, that.
* Casing, indentation, block alignment etc.: stick to the project's conventions.

Code convention always tend to be a sensitive topic among programmers as it calls
forth personal convictions and the weight of beloved traditions. As often,
preferences vary largely. With that, we humbly as you to be indulgent about the
choices made in this project.

* Symbol names, comments, file names etc. always in English.

* Casing, indentation, block alignment etc.: stick to the project's conventions.

* Comments are text. Use caption and punctuation accordingly.
* Comments are text. Use caption and punctuation accordingly.

This project uses clang-format for ensuring all code is equally formatted.

You can run `meson compile --ninja-args=clang-format` on your build directory
to format your changes.

Attribution and licensing
------------------------------

If you have substantially modified an existing source or documentation
file --- say it's considerably more than a simple typo correction or
small bug fix --- you are entitled to have your name added to the copyright
notice [1] and to the `AUTHORS` file, should you desire.

By submitting your contribution you agree that it will be available under the
same license as SYSeg (GNU GPL vr. 3 or later).

Contribution purpose
------------------------------

When applicable, use the following convention for commit messages and branch
names:

PERMANENT BRANCHES

The repository contains the two GitFlow permanent branches:

- `main` : the stable branch
- `develop` : the unstable branch (aka `develop`)
## Attribution and licensing

SUPPORT BRANCH NAMES (for PR/MR)
If you have substantially modified an existing source or documentation
file --- say it's considerably more than a simple typo correction or
small bug fix --- you are entitled to have your name added to the copyright
notice [1] and to the `AUTHORS` file, should you desire.

When creating an ephemeral branch, use the following keywords to indicate the
branch type (mind the casing):
By submitting your contribution you agree that it will be available under the
same license as SYSeg (GNU GPL vr. 3 or later).

- `feat` : extend of modify feature (GitFlow `feature`)
- `hot` : carry on maintenance on former releases (GitFlow `hotfix`)
- `rel` : prepare a new release (GitFlow `release`)
- `wip` : work-in-progress branch (unrelated to any issue)
- `adoc` : critical maintance bypassing the regular workflow
## Commit Messages

For `feat` and `hot` branches, use the scheme
We really value commit messages, we think it's the way of keeping record of the
project. Following the convention, the commit messages should not exceed 72
columns of text width.

```
<type>/<issue-number>/<short-descriptive-note>
```
Use lowercase alphanumeric ASCII characters, underscores, and hyphens in
place of spaces. No punctuation.
All the text should be on an imperative form, in a way that you're giving orders
to the project (e.g. "Fix spell error").

Example:
This is the commit message style we follow.

```
feat/42/modify-option-help
```gitcommit
[tag]: [Short description]

fix/66/crash-on-negative-input

```
It's usually preferrable that the PR/MR be linked to an existing issue.
Sometimes, however, we admit that ad hoc changes may be pragmatically
justifiable. In this case, if the PR/MR is not linked to an issue,
the simplified form

`<purpose>/<short-descriptive-mnemonic>`

is acceptable (this is most appropriate for 'wip' and 'exp' types).

For `rel` branches, use `rel/<release-number>`.
For `wip` and `adhoc`, use `<purpose>/<short-description>`
[Commit body]
```

COMMIT MESSAGES
### Tag

When editing the commit message, use the following keywords, inspired on a
lax version of Conventional Commits [4], to describe the purpose of your
contribution:

- `dev` : advance code (add of modify a feature)
- `fix` : fix a bug or an unmeat requirement.
- `ref` : refactor code for quality or compliance
- `doc` : modify or extend documentation
- `build` : improve the build process
- `repo` : tide up the repository and organization
- `minor` : something too simple as typo or cosmetics
- `other` : something else
It's serves for stating the area of the project were the commit is from. Usually
is a path to a directory of file, if in doubt of what tag to use, use `git log
<file>` in one of the files that you're touching.

The suggested commit messages is
### Short description

`<purpose> : short description`
It's meant to be a one-line summary of the changes. Do not try to describe
everything, you have less than 72 chars to work with. The commit body is for
that, just give a basic idea of what have been done.

where 'purpose' is one of the contribution purposes listed above.
Also, do not put a dot at the end of this line.

The short description should be in imperative form (fix, add, remove etc.)
rather than past (fixed, added) or present (fixes, adds) --- as if ordering
what the change should do (mind the capitalization). Do not punctuate.

Example:
### Commit body

```
fix: correct wrong file name
Here you explain the purpose of the commit: what's the problem, why it's needed
and how you solved it. Try to be very clear, as if you're describing to someone
that's doesn't knows about the issue you're solving. You can use markdown
notation if you want.

fix: add missing semicolon
The text should be on a time tense where the changes are not yet present on the
project, so for example, if you're describing a bug on the code you should not
write it in this way:

doc: update user manual
```
The code had a bug, so we fixed it.
```

repo: removed object files
Instead, this is the proper way:

```

Ideally, each commit should be of only one type. In practice, though,
it's reasonable to group changes in a single commit if they are naturally
related (e.g. you modifying a function's argument type and edit the developer
documentation to reflect the change). In those cases, it's ok to use
The code has a bug, so let's fix it.
```

```
<purpose 1> : short description 1

<purpose 2> : short description 2
...
```
If the commit solves an issue, please use a [closing keyword][closing-keyword]
on the commit body.

Purpose indication in commit messages is suggested, but not mandatory (if not
used, capitalize the first letter. Leave a blank line between statements.

If it helps to understand the context, do not refrain from adding a paragraph
further explaining the commit. This is normal text, so, capitalize and
punctuate accordingly.

If you're finding it difficult to write commit messages in this format, maybe
you're cramming too much stuff into a single commit, try splitting it into
smaller commits that do just one thing.

PR/MR MERGING

In the regular workflow, contributions in the form PR/MRs should be submitted
to the mainstream repository, then analyzed and merged into the destination
branch. Bypassing the regular protocols is exceptionally acceptable, at the
discretion of the project maintainers, to address urgent demands such as
critical repository maintenance or emergency bug fixes.
For more information on commit message guidelines, please follow this
[blogpost](https://cbea.ms/git-commit/).

## PR/MR merging

OTHER CONVENTIONS
Contributions should be done as a PR to the `develop` branch.

Compliance to Keep a ChangeLog [5] is under consideration.
All PR's that change the code in any functional way must come with a test using
the VUnit framework.

## Other conventions

References
------------------------------
Compliance to Keep a [ChangeLog][changelog] is under consideration.

[1] REUSE Software, https://reuse.software

[2] GitFlow, https://nvie.com/posts/a-successful-git-branching-model/
[reuse]: https://reuse.software

[3] Semantic Versioning, https://semver.org/
[git-flow]: https://nvie.com/posts/a-successful-git-branching-model/

[4] Conventional Commits, https://www.conventionalcommits.org/en/v1.0.0/
[semver]: https://semver.org/

[5] Keep a ChangeLog, https://keepachangelog.com/en/1.0.0/
[closing-keyword]: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword

[changelog]: https://keepachangelog.com/en/1.0.0/