Skip to content

Commit 6abb5a6

Browse files
committed
[DOCS] Contributing guidelines first draft
1 parent c455e60 commit 6abb5a6

1 file changed

Lines changed: 61 additions & 0 deletions

File tree

CONTRIBUTING.md

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# CANopenEditor Contributing Guidelines
2+
3+
Thank you for your interest in contributing to this project !
4+
Being a well referenced EDS/DCF editor and the only one supporting CANopenNode, CANopenEditor let everyone manage CANopen files, completely free of charge !
5+
CANopenEditor is maintained by a small team of volunteers from around the world. As such, those rules are meant for a better communication between everyone but, any help being very welcome, reviewers might approve PRs not respecting all of these rules as long as you tried.
6+
Also, those rules do not apply to code owners (as they might have specific needs) and might change.
7+
Please note that by contributing to this project, you agree to have read this file and to the [Developer's Certificate of Origin 1.1](https://developercertificate.org/)
8+
9+
## Discussions
10+
Discussions shall be done in respect to everyone and everyone's work.
11+
Any major change shall be first discussed in an issue. Do not worry: maintainers are quite active and will answer.
12+
13+
## Code convention
14+
This project doesn't really follow any real code convention and doesn't have any linter for now BUT following [common C# code conventions](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions) is very welcome and might be asked of you if some parts of your code is too hard to read.
15+
If linting is ever needed, `dotnet format` will be our solution of choice.
16+
Even tho there is no hard defined conventions, non-explicit names or lack of spacing might result in non-approval of a PR.
17+
18+
## What might or might not be a PR
19+
A simple refactor of code without any real change won't ever be approved. This project relies quite a bit on git blame and as such you are only allowed to refactor code you change. Moreover, trying to enforce a code convention with approval of the main maintainers first might be seen as disrespectful.
20+
21+
## Testing
22+
Any code change shall be tested. You can:
23+
- Add unit tests in the right directories
24+
- Describe any tests you did with the files you might have used
25+
Code that you didn't even try to compile won't be accepted.
26+
27+
## Code comments
28+
Complex algorithms MUST be explained with code comments.
29+
Hardcoded values (e.g. specific numbers in the middle of nowhere) MUST be justified with code comments.
30+
Non explicit data structures (e.g. an array of set size with every index having a meaning) MUST be explained with code comments.
31+
Commented lines of code MUST be preceded by a comment line starting with either `//// DEBUG code:` or `//// TODO:`.
32+
Comments SHALL have a space between the comment string (e.g. `//`) and the text.
33+
Functions and methods MIGHT have comments describing what they are doing, what are their inputs and/or outputs (if it's not explicit enough).
34+
Loops and switches MIGHT have comments justifying why every case is taken into account (if it's not explicit enough).
35+
Any more useful comment is welcome.
36+
37+
## Names and descriptions
38+
### PR names
39+
They shall be composed of three sections:
40+
1) Which project is affected (MIX if multiple)
41+
2) What types of changes are made (e.g. FEAT, FIX, DOCUMENTATION/DOC, CORRECTION/CORR, SUGGESTION/SUGG, BUILD, ...)
42+
3) An explicit but less than 100 chars long summary of the changes
43+
Sections shall be clearly separated (e.g. with colons, parenthesis, ...).
44+
Example of valid and explicit PR name: `[MIX][DOC] Explaining explicit PR title rules`.
45+
If you have multiple unrelated changes (e.g. adding a feature and fixing another) to do, please do multiple PRs.
46+
47+
### PR descriptions
48+
They shall:
49+
- Describe any change made
50+
- Explain why such changes are made
51+
- Explain any decision taken
52+
- Link any related issue / any related other PR
53+
- Describe any test made
54+
- The sentence "I have read the contributing guidelines, I agree to following them and I agree to the Developer's Certificate of Origin 1.1"
55+
56+
### Commits
57+
Names shall be composed of:
58+
2) What types of changes are made
59+
3) An explicit but less than 100 chars long summary of the changes
60+
61+
Descriptions are entirely up to you.

0 commit comments

Comments
 (0)