From 7b3020497d728b92482fe07f8a212a5ffa142785 Mon Sep 17 00:00:00 2001 From: Arthur Grillo Date: Mon, 27 Jan 2025 16:47:48 -0300 Subject: [PATCH 01/10] docs/CONTRIBUTING.md: Use the more usual heading convention For standardization and simplicity let's use the more common header notation style. --- docs/CONTRIBUTING.md | 27 ++++++++++----------------- 1 file changed, 10 insertions(+), 17 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index f04be7c..65a0e91 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,13 +1,11 @@ -Contributing to Vinum -============================== +# Contributing to Vinum Vinum is open source and you are welcome and encouraged to contribute. These are a few guidelines. - Contribution workflow - ------------------------------ +## Contribution workflow The official Vinum repository is at https://github.com/monacofj/Vinum @@ -39,9 +37,8 @@ Contributing to Vinum 5. Go have a cup of wine, as you’ve earned it. - Project standards - ------------------------------ - +## Project standards + To keep things consistent, when applicable, we aim at some some standards. - REUSE specification vr. 3 [1] @@ -50,8 +47,7 @@ Contributing to Vinum - Semantic versioning 2.0.0 [3] - Code convention - ------------------------------ +## Code convention Oh, that. @@ -71,8 +67,7 @@ Contributing to Vinum You can run `meson compile --ninja-args=clang-format` on your build directory to format your changes. - Attribution and licensing - ------------------------------ +## 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 @@ -82,8 +77,7 @@ Contributing to Vinum 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 - ------------------------------ +## Contribution purpose When applicable, use the following convention for commit messages and branch names: @@ -192,7 +186,7 @@ Example: punctuate accordingly. - PR/MR MERGING +## 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 @@ -201,13 +195,12 @@ Example: critical repository maintenance or emergency bug fixes. - OTHER CONVENTIONS +## Other conventions Compliance to Keep a ChangeLog [5] is under consideration. -References - ------------------------------ +# References [1] REUSE Software, https://reuse.software From 8288e833544a3781ccc2e5f5dc427ae8b0ff9504 Mon Sep 17 00:00:00 2001 From: Arthur Grillo Date: Mon, 27 Jan 2025 16:53:05 -0300 Subject: [PATCH 02/10] docs/CONTRIBUTING.md: Remove indentation Indentation in this case just makes it harder to read and write the raw file, just remove it. --- docs/CONTRIBUTING.md | 261 +++++++++++++++++++++---------------------- 1 file changed, 126 insertions(+), 135 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 65a0e91..8b4752d 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,27 +1,26 @@ - # Contributing to Vinum - - Vinum is open source and you are welcome and encouraged to contribute. - These are a few guidelines. +Vinum is open source and you are welcome and encouraged to contribute. + +These are a few guidelines. ## 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 + +To start contributing, make sure you've read the essential documentation +thoroughly: + + - `docs/vinum.md + - `docs/CONTRIBUTING.md` + -- docs/CODE_OF_CONDUCT.md - - `docs/vinum.md - - `docs/CONTRIBUTING.md` - -- docs/CODE_OF_CONDUCT.md +Then, go through the following steps. - Then, go through the following steps. +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. - 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: +3. If you want to contribute a solution for that issue: * fork the project * create a local branch for the issue (see branch naming below). @@ -30,37 +29,32 @@ * push your branch into your repository * got to github and make it into a pull/merge request - Do not submit a PR/MR that is not related to an open issue. +5. Go have a cup of wine, as you’ve earned it. - 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. +## Project standards - 5. Go have a cup of wine, as you’ve earned it. +To keep things consistent, when applicable, we aim at some some standards. -## Project standards - - To keep things consistent, when applicable, we aim at some some standards. +- REUSE specification vr. 3 [1] - - REUSE specification vr. 3 [1] - - - GitFlow branching strategy [2] +- GitFlow branching strategy [2] - - Semantic versioning 2.0.0 [3] +- Semantic versioning 2.0.0 [3] ## Code convention - Oh, that. +Oh, that. + +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 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. +* Symbol names, comments, file names etc. always in English. - * Casing, indentation, block alignment etc.: stick to the project's conventions. +* 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. @@ -69,146 +63,143 @@ ## 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. +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). +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: +When applicable, use the following convention for commit messages and branch +names: - PERMANENT BRANCHES +PERMANENT BRANCHES - The repository contains the two GitFlow permanent branches: - - - `main` : the stable branch - - `develop` : the unstable branch (aka `develop`) +The repository contains the two GitFlow permanent branches: - SUPPORT BRANCH NAMES (for PR/MR) +- `main` : the stable branch +- `develop` : the unstable branch (aka `develop`) - When creating an ephemeral branch, use the following keywords to indicate the - branch type (mind the casing): +SUPPORT BRANCH NAMES (for PR/MR) - - `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 +When creating an ephemeral branch, use the following keywords to indicate the +branch type (mind the casing): - For `feat` and `hot` branches, use the scheme +- `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 - ``` - // - ``` - Use lowercase alphanumeric ASCII characters, underscores, and hyphens in - place of spaces. No punctuation. +For `feat` and `hot` branches, use the scheme - Example: +``` +// +``` +Use lowercase alphanumeric ASCII characters, underscores, and hyphens in +place of spaces. No punctuation. + + Example: - ``` - feat/42/modify-option-help +``` +feat/42/modify-option-help + +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 - 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 - - `/` +is acceptable (this is most appropriate for 'wip' and 'exp' types). - is acceptable (this is most appropriate for 'wip' and 'exp' types). +For `rel` branches, use `rel/`. +For `wip` and `adhoc`, use `/` - For `rel` branches, use `rel/`. - For `wip` and `adhoc`, use `/` +COMMIT MESSAGES - COMMIT MESSAGES +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: - 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 +- `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 - The suggested commit messages is +The suggested commit messages is - ` : short description` +` : short description` - where 'purpose' is one of the contribution purposes listed above. +where 'purpose' is one of the contribution purposes listed above. + +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. - 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: - ``` - fix: correct wrong file name +``` +fix: correct wrong file name + +fix: add missing semicolon - fix: add missing semicolon +doc: update user manual - doc: update user manual +repo: removed object files +``` - repo: removed object files +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 ``` - - 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 - - ``` - : short description 1 - - : short description 2 - ... - ``` - - 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. - + : short description 1 + + : short description 2 +... +``` + +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. + ## 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. + +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. ## Other conventions - Compliance to Keep a ChangeLog [5] is under consideration. +Compliance to Keep a ChangeLog [5] is under consideration. # References - [1] REUSE Software, https://reuse.software - - [2] GitFlow, https://nvie.com/posts/a-successful-git-branching-model/ +[1] REUSE Software, https://reuse.software - [3] Semantic Versioning, https://semver.org/ +[2] GitFlow, https://nvie.com/posts/a-successful-git-branching-model/ - [4] Conventional Commits, https://www.conventionalcommits.org/en/v1.0.0/ +[3] Semantic Versioning, https://semver.org/ - [5] Keep a ChangeLog, https://keepachangelog.com/en/1.0.0/ +[4] Conventional Commits, https://www.conventionalcommits.org/en/v1.0.0/ +[5] Keep a ChangeLog, https://keepachangelog.com/en/1.0.0/ From 4092754a70a9ade6e455c8f2057c1b6dedd41d4a Mon Sep 17 00:00:00 2001 From: Arthur Grillo Date: Mon, 27 Jan 2025 16:56:36 -0300 Subject: [PATCH 03/10] docs/CONTRIBUTING.md: Fix documentation list The list has a wrong item syntax on the end and also doesn't have a link to the files. --- docs/CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 8b4752d..0f86133 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -11,9 +11,9 @@ The official Vinum repository is at https://github.com/vinumdoc/vinum To start contributing, make sure you've read the essential documentation thoroughly: - - `docs/vinum.md - - `docs/CONTRIBUTING.md` - -- docs/CODE_OF_CONDUCT.md + - [vinum.md](/docs/vinum.md) + - [CONTRIBUTING.md](/docs/CONTRIBUTING.md]) + - [CODE_OF_CONDUCT.md](/docs/CODE_OF_CONDUCT.md) Then, go through the following steps. From 59c49fdb64b4f46804c565a5c2b461131ee72a33 Mon Sep 17 00:00:00 2001 From: Arthur Grillo Date: Mon, 27 Jan 2025 16:26:48 -0300 Subject: [PATCH 04/10] docs/CONTRIBUTING.md: Remove branch naming rule I realy don't care how you name your PR branches, they are ephemeral. --- docs/CONTRIBUTING.md | 54 +++----------------------------------------- 1 file changed, 3 insertions(+), 51 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 0f86133..52f5b5e 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -23,7 +23,7 @@ Then, go through the following steps. 3. If you want to contribute a solution for that issue: * fork the project - * create a local branch for the issue (see branch naming below). + * create a local branch for the issue. * 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 @@ -71,57 +71,9 @@ 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 +## Commit Messages -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`) - -SUPPORT BRANCH NAMES (for PR/MR) - -When creating an ephemeral branch, use the following keywords to indicate the -branch type (mind the casing): - -- `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 - -For `feat` and `hot` branches, use the scheme - -``` -// -``` -Use lowercase alphanumeric ASCII characters, underscores, and hyphens in -place of spaces. No punctuation. - - Example: - -``` -feat/42/modify-option-help - -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 - -`/` - -is acceptable (this is most appropriate for 'wip' and 'exp' types). - -For `rel` branches, use `rel/`. -For `wip` and `adhoc`, use `/` - -COMMIT MESSAGES +When applicable, use the following convention for commit messages: When editing the commit message, use the following keywords, inspired on a lax version of Conventional Commits [4], to describe the purpose of your From 74c43746d58efab83045bfa6cba19a6eda556e38 Mon Sep 17 00:00:00 2001 From: Arthur Grillo Date: Mon, 27 Jan 2025 16:36:24 -0300 Subject: [PATCH 05/10] docs/CONTRIBUTING.md: Change commit message guidelines I think these tags fill up the first commit line than they give some useful information. Also the commit message guidelines are not descriptive enough. Try to write a better guideline following this great blogpost[1]. [1]: https://cbea.ms/git-commit/ --- docs/CONTRIBUTING.md | 79 +++++++++++++++++++++++--------------------- 1 file changed, 41 insertions(+), 38 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 52f5b5e..6266624 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -73,62 +73,65 @@ same license as SYSeg (GNU GPL vr. 3 or later). ## Commit Messages -When applicable, use the following convention for commit messages: +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. -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: +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"). -- `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 +This is the commit message style we follow. -The suggested commit messages is +```gitcommit +[tag]: [Short description] -` : short description` +[Commit body] +``` -where 'purpose' is one of the contribution purposes listed above. +### Tag -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. +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 +` in one of the files that you're touching. -Example: +### Short description -``` -fix: correct wrong file name +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. -fix: add missing semicolon +Also, do not put a dot at the end of this line. -doc: update user manual +### Commit body -repo: removed object files -``` +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. -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 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: ``` - : short description 1 +The code had a bug, so we fixed it. +``` + +Instead, this is the proper way: - : short description 2 -... +``` +The code has a bug, so let's fix it. ``` -Purpose indication in commit messages is suggested, but not mandatory (if not -used, capitalize the first letter. Leave a blank line between statements. +If the commit solves an issue, please use a [closing keyword][closing-keyword] +on the commit body. -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. +For more information on commit message guidelines, please follow this +[blogpost](https://cbea.ms/git-commit/). ## PR/MR merging @@ -152,6 +155,6 @@ Compliance to Keep a ChangeLog [5] is under consideration. [3] Semantic Versioning, https://semver.org/ -[4] Conventional Commits, https://www.conventionalcommits.org/en/v1.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 [5] Keep a ChangeLog, https://keepachangelog.com/en/1.0.0/ From 44ee32bb9dad18458d8fc2bb370dcb4021043a66 Mon Sep 17 00:00:00 2001 From: Arthur Grillo Date: Wed, 29 Jan 2025 23:22:15 -0300 Subject: [PATCH 06/10] docs/CONTRIBUTING.md: Remove obligatory issue creation I don't think is necessary to create an issue before doing an PR, it just make the contribution process more cumbersome. --- docs/CONTRIBUTING.md | 24 ++++++++---------------- 1 file changed, 8 insertions(+), 16 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 6266624..9635c48 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -7,7 +7,7 @@ These are a few guidelines. ## Contribution workflow The official Vinum repository is at https://github.com/vinumdoc/vinum - + To start contributing, make sure you've read the essential documentation thoroughly: @@ -15,21 +15,13 @@ thoroughly: - [CONTRIBUTING.md](/docs/CONTRIBUTING.md]) - [CODE_OF_CONDUCT.md](/docs/CODE_OF_CONDUCT.md) -Then, go through the following steps. - -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: - - * fork the project - * create a local branch for the issue. - * 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 - -5. Go have a cup of wine, as you’ve earned it. +1. Fork the project +1. Create a local branch for the issue. +1. Edit the relevant files in the branch +1. run `meson compile --ninja-args=clang-format` to format your code changes +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 ## Project standards From 03e3b2f72872f1cb2cec34a9be7de9ed692739df Mon Sep 17 00:00:00 2001 From: Arthur Grillo Date: Wed, 29 Jan 2025 23:33:28 -0300 Subject: [PATCH 07/10] docs/CONTRIBUTING.md: Remove PR bypassing rule We don't need this exception, every contribution must pass the same process. --- docs/CONTRIBUTING.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 9635c48..c5596d0 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -129,10 +129,7 @@ For more information on commit message guidelines, please follow this 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. - +branch. ## Other conventions From 384bbc12688a2c254d812dead296914b07bff389 Mon Sep 17 00:00:00 2001 From: Arthur Grillo Date: Thu, 30 Jan 2025 16:28:43 -0300 Subject: [PATCH 08/10] docs/CONTRIBUTING.md: Improve the PR merging section Be more specific about what is the target branch to use. And also write that the tests are obligatory for a PR to be accepted. --- docs/CONTRIBUTING.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index c5596d0..2d9f408 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -127,9 +127,10 @@ For more information on commit message guidelines, please follow this ## 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. +Contributions should be done as a PR to the `develop` branch. + +All PR's that change the code in any functional way must come with a test using +the VUnit framework. ## Other conventions From 837d79f2fd2ec9b12a99f63fe817b66233f45ae3 Mon Sep 17 00:00:00 2001 From: Arthur Grillo Date: Thu, 30 Jan 2025 16:42:50 -0300 Subject: [PATCH 09/10] docs/CONTRIBUTING.md: Set references as links Markdown has a feature to make links, let's use it instead of having a list of references. --- docs/CONTRIBUTING.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 2d9f408..7285fe4 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -27,11 +27,11 @@ thoroughly: To keep things consistent, when applicable, we aim at some some standards. -- REUSE specification vr. 3 [1] +- [REUSE specification vr. 3][reuse] -- GitFlow branching strategy [2] +- [GitFlow branching strategy][git-flow] -- Semantic versioning 2.0.0 [3] +- [Semantic versioning 2.0.0][semver] ## Code convention @@ -134,17 +134,15 @@ the VUnit framework. ## Other conventions -Compliance to Keep a ChangeLog [5] is under consideration. +Compliance to Keep a [ChangeLog][changelog] is under consideration. -# References +[reuse]: https://reuse.software -[1] REUSE Software, https://reuse.software +[git-flow]: https://nvie.com/posts/a-successful-git-branching-model/ -[2] GitFlow, https://nvie.com/posts/a-successful-git-branching-model/ - -[3] Semantic Versioning, https://semver.org/ +[semver]: https://semver.org/ [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 -[5] Keep a ChangeLog, https://keepachangelog.com/en/1.0.0/ +[changelog]: https://keepachangelog.com/en/1.0.0/ From fbdface15ab0c64e54f367c14e058fc28af9e816 Mon Sep 17 00:00:00 2001 From: Arthur Grillo Date: Thu, 30 Jan 2025 17:26:10 -0300 Subject: [PATCH 10/10] docs/CONTRIBUTING.md: Add a link to the build steps in the README.md This is done to remove redundant information. --- docs/CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 7285fe4..559b6ba 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -18,7 +18,8 @@ thoroughly: 1. Fork the project 1. Create a local branch for the issue. 1. Edit the relevant files in the branch -1. run `meson compile --ninja-args=clang-format` to format your code changes +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