docs: contribution guide. #222
Conversation
|
First feedback from @jonathlela and response: |
| - refactor/refactor-kernels | ||
| - docs/contribution-guide-doc | ||
|
|
||
| ### Installation |
There was a problem hiding this comment.
should we put this in two different places ? we can forgot to update
There was a problem hiding this comment.
The entire installation? I agree, I think this kind of information should be centralized in one place. Currently it is in the README and not in the doc. We can refer to the README here.
|
|
||
| ??? example "@reviewer: proposal to be validated" | ||
| ``` | ||
| @team: what about creating a dedicated discussion forum? |
There was a problem hiding this comment.
IMO discussion in Github is nice: the only thing, is that it is sometimes badly used (like it is used as issues and the inverse)
There was a problem hiding this comment.
You are right. Maybe it is overkill at this point. It is more to avoid discussion issues.
| options: | ||
| - label: I would be willing to contribute to this issue myself. | ||
|
|
||
| - type: checkboxes |
There was a problem hiding this comment.
utile une checkbox pour ça ?
There was a problem hiding this comment.
This is a practice seen to identify a person ready to really contribute. Tell me if it's overkill or too restrictive.
This PR adds the contribution guide to the kernl site.
Main changes
Other changes:
Some comments on PR
From what I've seen and read, there seem to be different ways to write a contribution guide. It depends on our goal.
Like some Open Source projects (like Docusaurus, React, ...), I took the part to be not too technical, not too hard, but rather to be "welcoming" and guiding.
My motivation is that I feel like it's a bit like the TOS (CGU), I'm not sure if everyone reads it.
For this reason, I propose to have a rather simple contribution guide and to frame with Github form templates (in beta) for the different issues. I am aware that this is a strong bias that can impact you too (except for leaving a "free" issue).
In addition to these templates, it is an idea, to avoid having sometimes too vague issues, to redirect to a discussion forum in the repo. This allows to deal with features that are too vague or simple ideas. It avoids blocking the tracker issue if the project changes scale. Again, I'm aware that this may impose too much effort on the team.
I encourage you to review the documentation in preview mode.About contributing
I don't know if it's obvious, but I thought it would be useful to add an on-boarding page for the contribution. It allows to welcome everyone, including contributors who would not be experts (e.g. motivated users). It also allows to relay the spirit of what we say on the landing page.
Please give me a feedback on this.About the code of conduct
After much reading, I understand that it is possible to write your own code of conduct. However, most of the time it is a general document regulating behaviours with graduated sanctions.
There is a code of conduct on which many adopters rely, including github, React, etc. : https://www.contributor-covenant.org/.
This is the one I propose to adopt (in version 2.1).
A code of conduct that is not (or cannot be) enforced is worse than no code of conduct: it sends the message that the values of the code of conduct are not really important or respected in our community.
For this reason it is necessary to offer a way to report a violation of the code of conduct. I have put, in the C.O.C, the
open.kernl.ai@gmail.comemail that we should consult (or be notified). We could also create a dedicated address such as :open.kernl.ai.conduct@gmail.com.Please give me a feedback on this.Finally, it should be noted that a good practice is to put the C.O.C at the root of the repo. This allows Github to detect it and mention it on the right side of the repo. in the community section.
About How to contribute
I've been focusing mainly on the means of contributions. Different Issues, Pull Requests, branches. Some of the contribution guides say how to install the project, test, etc. I don't know if that's where we want to put that or if it's elsewhere in the documentation.
This is something to discuss and iterate on.
In the meantime I have taken over the sections of the README.
Do not hesitate to give me your opinionFeedbacks
https://elsitlab.slack.com/archives/C02VD0MUZFS/p1673016387993709?thread_ts=1672999314.406399&cid=C02VD0MUZFS
fix #189