|
| 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