From c32b9445356126e63e0a9ff185feb35dd3e5f856 Mon Sep 17 00:00:00 2001 From: Felix Walter Date: Thu, 4 Jan 2024 10:01:34 +0100 Subject: [PATCH] Add merge request template and contribution guidelines Signed-off-by: Felix Walter --- .gitlab/merge_request_templates/MR.md | 42 +++++++++++++++ CONTRIBUTING.md | 73 +++++++++++++++++++++++++++ 2 files changed, 115 insertions(+) create mode 100644 .gitlab/merge_request_templates/MR.md diff --git a/.gitlab/merge_request_templates/MR.md b/.gitlab/merge_request_templates/MR.md new file mode 100644 index 0000000..fb4aa8e --- /dev/null +++ b/.gitlab/merge_request_templates/MR.md @@ -0,0 +1,42 @@ +# Description + + + + + +Closes: (Issue id) + +# Checklist for MR author + + + +- :white_check_mark: This MR does not introduce **backwards-incompatible API changes**. + + +- :white_check_mark: This MR does not introduce new functionality without corresponding **tests**. It does not break or disable existing tests. + + +- :white_check_mark: I am not aware of new interactions that could be prone to **race conditions**. + + +- :white_check_mark: I have no **security related reservations or thoughts** I would like to share about the changes introduced by this MR. + + +- :white_check_mark: The **documentation** (architecture, developer, operator, user) is in line with the changes in the MR. + + +- :white_check_mark: My contribution adheres to the [**Contribution Guidelines**](CONTRIBUTING.md). + Specifically: + - I provide my contribution under the terms and conditions of the [Apache 2.0 license](LICENSE.Apache-2.0). I am aware of the patent grant that is part of this license and certify conformance. + - I certify conformance with the [DCO](DCO.txt). All commits contain the corresponding signoff line. + - I am aware that my contribution will become part of µD3TN, which is currently dual-licensed under [AGPLv3](LICENSE) and a proprietary license offered by D3TN, and may potentially become part of software using other compatible licensing schemes in the future. + +# Checklist for MR reviewers + +Note: Approving the MR is equivalent to confirming all items below. + +- I reviewed the changes. +- I reviewed the commits. +- I reviewed the statements made above; they are correct as far as I can judge. I have nothing to criticize. +- New code in core components has good testability. +- I reviewed the related Issue(s). The stated tasks have been addressed and the changes reflect the issue decisions. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eafd3fa..6cd4742 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,6 +24,9 @@ contact the maintainers directly. - Before you create a merge request, please make sure that the subject of change is covered by an issue. +- Please take note of the conventions noted below and make sure to apply them + if possible. Deviations are fine as long as they are reasonably explained in + the merge request and the reviewers agree to that reasoning. - Only submissions conformant to the *Developer Certificate of Origin* can be accepted into µD3TN. Please see the DCO Version 1.1 for details, available at or via https://developercertificate.org/. @@ -39,3 +42,73 @@ contact the maintainers directly. open-source or proprietary license that is compatible. This includes the currently-used AGPLv3 license of the µD3TN project and D3TN's proprietary licensing scheme for closed-source products. +- Please use the provided [merge request template](.gitlab/merge_request_templates/MR.md). + +## Coding Guildelines + +* Declare and document public interfaces cleanly +* Use constants whenever possible +* Avoid global state +* Provide appropriate tests along with new functionality +* Avoid complicated, complex, license-wise incompatible, or unmaintained + dependencies +* Care for POSIX compatibility (e.g., Linux-only features can be disabled during + build) +* Respect the [Linux Kernel Coding Style](https://www.kernel.org/doc/html/v5.7/process/coding-style.html) + for C and [PEP8](https://www.python.org/dev/peps/pep-0008/) for Python + +## Git(Lab) Workflow Guidelines + +### Issues + +* Titles of issues should preferably describe the _issue_ +* Explain what should be done and why +* Reference any other issue and merge request(s) at the bottom + +### Branches + +* Format branch names like this: `/-short-description`, whereas + - `` is one of `hotfix` and `feature`, and + - `issue ID` should reference something from the + [issue tracker](https://gitlab.com/d3tn/ud3tn/-/issues) -- if there is no + issue, create one or drop that part including the dash +* Keep feature branches atomic if possible (one branch and merge request per + feature / issue) + +### Merge Requests + +* Think about creating issues before submitting merge requests; if there is no issue, document the reason for the change +* Titles of merge requests should be in imperative mood like commit headings (see below) +* Keep merge requests in [`Draft` state](https://docs.gitlab.com/ee/user/project/merge_requests/drafts.html) (`WIP` is deprecated) as long as something is blocking them +* Explain what should be/has been done and why +* Reference any other issue and merge request(s) at the bottom +* Always assign merge requests to somebody (the one who should work/act on it next) + +### Commits + +* [Write good commit messages](https://chris.beams.io/posts/git-commit) +* Title: Use a short, descriptive title and [sentence case](https://en.wikipedia.org/wiki/Letter_case#Sentence_case) + without a dot at the end +* Explain what has been done and why +* Merge commits should contain a reference to any existing merge request in the + description +* Merge commits that update a *feature* branch with new commits from `master` + should mention why they are necessary (why `git rebase` was not used) +* Refer to the issue tracker if possible +* Add a sign-off line to your commits to declare conformity with these rules, + do NOT sign the commits with GPG to facilitate easy rebases by others + +An ideal commit should look similar to the following: + +``` + + +<WHAT HAS BEEN CHANGED> + +<WHY HAS THIS BEEN CHANGED / WHAT PROBLEM IS SOLVED WITH THE CHANGE> + +<OTHER REMARKS / IMPLEMENTATION TRADE-OFFS> + +Closes: <REFERENCE ISSUES THAT ARE RESOLVED WITH THIS OR RELATED> +<SIGN-OFF> +```