diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000000000000000000000000000000000..bfcfdd24b8b07a26dd321a9806a430922a6e681a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,54 @@ +# Contributing + +Before contributing, please make sure that your development environment is properly configured. + +When contributing to this repository, please first discuss the change you wish to make via issue and +via [the technical forum] before making a change. + +Please note we have a specific workflow, please follow it in all your interactions with the project. + +## Workflow + +- You must create an issue for each feature you wish to develop, with a precise title and a + description of your feature. Then, assign it to yourself and click on the button + **`Create a merge request`**. GitLab will create a branch dedicated to the issue as well as a + *Work in Progress* merge request of this branch into the main branch (`master`). +- Please use tags to specify feature domains and concerned modules. +- Write your code according to [project conventions]. +- Never contribute to a branch whose issue has not been assigned to you! If the contributor make a + `git rebase` your commit will be lost ! +- Before you push your commit: + - Document your code. + - Write unit tests, and verify that they **all** pass. + - Apply the [project's git conventions] + +## Project conventions + +- Name your variables and types with long and explicit names. We must understand what is contained in a type or a variable by just reading its name (without looking for the definition or the initialization). +- Variables containing an Option must be suffixed `_opt`. +- Variables containing a Result must be set to `_res`. +- 400 lines per file maximum (excluding tests) +- Cut to the maximum in sub-modules +- When your command provides an interactive view. Separate the view from the logic by creating a struct/enum suffixed `View` that contains all the data to be displayed. +- Test everything that is testable. If your code is not testable, refactor it to extract the logic in pure functions. + +## Merge Process + +1. Ensure you rebased your branch on the latest `master` commit to avoid any merge conflicts. + +2. Ensure that you respect the [commit naming conventions]. + +3. Ensure that all automated tests pass with the `cargo test --all` command. + +4. Push your branch on the gitlab. Briefly explain the purpose of your contribution in the description of the merge request. + +5. Tag a ğcli reviewer so he will review your contribution. If you still have no news after several weeks, tag another reviewer or/and talk about your contribution on [the technical forum]. + +## List of ğcli's reviewers + +- @librelois + +[the technical forum]: https://forum.duniter.org +[project conventions]: #project-conventions +[project's git conventions]: ./doc/git-conventions.md +[commit naming conventions]: ./doc/git-conventions.md#naming-commits diff --git a/doc/git-conventions.md b/doc/git-conventions.md new file mode 100644 index 0000000000000000000000000000000000000000..5af72bf44f4ca499537e2e537f50ff29a9103cf0 --- /dev/null +++ b/doc/git-conventions.md @@ -0,0 +1,131 @@ +# Ğcli git conventions + +## TL;DR summary of this page, workflow instructions + +The summary gives an overview of the rules described below. Reading it will help you to dive into the details. + +- Branches must be named according to the template `type/description` +- draft work must be prefixed by "WIP" (work in progress) +- the naming of final commits must comply with the template `type(scope): action subject` +- one should communicate with developers through dedicated spaces +- integrating a contribution can only be done via a rebase and since the following critera are fullfilled + - branch up to date with `master` branch + - idiomatic code formatting, automated tests passed successfully + - clean commit history, understandable and concise + - contribution approved by a reviewer + +## Naming commits + +Every commit must follow this convention: + + type(scope): action subject + +The **type** must be a keyword of the "Commit types" list below. + +The **scope** must be the name of the module in question. + +The **action** must be a verb in imperative form, the **subject** a noun. + +For example, we rename the trait `Foo` to `Fii` in the `toto` module: + + ref(toto): rename Foo -> Fii + +Commits must be lowercase. + +### Commit types + +- `build`: Changes in the scripts of build, packaging or publication of releases. +- `ci` : Changes in the Continuous Integration pipeline. +- `deps` : Changes in dependencies without changes into the code. This can be for update or deletion of third-party libraries. +- `docs` : Changes in documentation (both for translation and new content). +- `feat` : Development of a new feature. +- `fix` : Bug fixing. +- `git` : Changes `.gitignore` or git hooks. +- `opti` : Optimisation: better performances, decrease in memory or disk usage. +- `ref` : Refactoring. This commit doesn't change the functionnality. +- `style` : Style modification (usually `fmt` and `clippy`). +- `tests` : Changes in tests or new tests. + +The commit name hase to be meaningful in the context of commit history reread. It should not make reference to a specific MR or discussion. +Among other, commit history is used in changlogs and to follow the project progress, that's why it has to be self-explanatory. +If you have a new need, please contact the main developers to add a type together. + +## Update strategy + +We only use **rebases**, *merges* are strictly fordbidden ! + +Every time the `master` branch is updated, you must rebase each of your working branch on it. For each of them: + +1. Go on your branch +2. Run a rebase on master: + + git rebase master + +3. If you see conflicts, fix them by editing the sources. Once it is done, you must: + a. commit the files that were in conflict + b. continue the rebase with `git rebase --continue` + c. Do 3. again for each commit that will be in conflict. + +4. When you don't have any conflict anymore after `git rebase --continue`, then the rebase succeeded. Then rebase a remaning branch. + +To prevent accidental merge commits, we recommend that force the `--ff-only` option on the merge command: + + git config --global merge.ff only + +## When to push + +Ideally, you should push when you are about to shut down your computer, so about once a day. + +You must prefix your commit with `wip:` when it is a work in progress. + +> But why push if I am not done ? + +Pushing is no big deal and prevents you from loosing work in case of +any problem with your material. + +## Before requesting proofreading of your merge request + +After complying with the above criteria in your commits, you should check that your branch is up to date with the target branch (`master` in this example). As this branch is moving forward frequently, it is possible that new commits may have occurred while you were working on your branch (named YOUR_BRANCH, here). If this is the case or in case of doubt, to update your branch with respect to `master`, do the following: + + git checkout master # switch to master branch + git pull # updates the remote branch based on remote + git checkout YOU_BRANCH # switch back to your branch + git rebase master # rebase you work on master branch + +In case of conflict during rebase that you can not solve, contact a lead developer telling him the hash of the commit on which YOUR_BRANCH is currently based so he can reproduce the rebase and see the conflicts. While waiting for his answer, you can cancel the rebase and work on YOUR_BRANCH without updating: + + git rebase --abort + +It is better to take your time before integrating a new contribution because the history of the master branch cannot be modified: it is a protected branch. Each commit on this branch remains there *ad vitam aeternam* that is why we make sure to keep a clear and understandable commit history. + +## Discussion in a merge request + +On Gitlab, a discussion is opened for each merge request. It will allow you to discuss the changes you have made. Feel free to identify someone by writing @pseudo so that they are notified of your request. Don't be impatient, the review of your contribution may take more or less time depending on its content! + +The general discussion is used to comment on the merge request as a whole, for example to tag a developer for a proofreading request. When it comes to discussing a specific change in the code, you should go to the "Changes" tab of the merge request and comment under the code extract involved. This makes it easier to break down the resolution of problems raised by the merge request via the "comment resolution" feature. Each segment can be marked as resolved, but only the reviewer is allowed to do so! + +## How to merge + +When you finished developing, you must compile, run linter and run all tests: + + cargo fmt + cargo clippy -all --tests + cargo test --all + +Then commit everything. + +In case you had a `wip:` prefix, you can remove it. + +If you have a pile of commits, use the useful interactive rebase to clean up your branch history and create atomic ones: + + git rebase -i master + +There you can rename the `wip:` commits, you can "fixup" commits that go together, you can rename and re-order commits,... + +After an interactive rebase, your local git history is different that yours in Gitlab, so you need a force push to make it to Gitlab: + + git push -f + +Now is time to go to Gitlab and re-check your commits. + +Wait for the Continuous Integration pipeline to finish (it lasts ±20min), and at last when it is done you can remove the "WIP" mention of your Merge Request and mention (with "@name") the lead developers to ask for a code review.