[WIP] Add an AI Guideline for OpenCloud plus minor adjustments in README #29
+70
−11
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,63 @@ | ||||||
|
|
||||||
| # AI Contributions | ||||||
|
|
||||||
| AI usage is causing challenges for all open source projects, so for OpenCloud. | ||||||
| This document will set up guidelines how we work with AI and how we ask contributors to work with it. | ||||||
|
|
||||||
| This is done to protect OpenCloud, especially with regards to the following points: | ||||||
|
|
||||||
| 1. **Code Quality**: OpenCloud has a strong focus on code quality as we know that dealing with users data comes with a great responsibility for data security. All contributions have to put that first. | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
| 2. **Focus**: OpenCloud serves a certain purpose which is defined very carefully by product managenment. All contributions have to align with that roadmap. | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
| 3. **Maintainability**: All contributions must be as "consumable" as ever possible since all contributions will be reviewed. Also, code that is written today needs to be maintained tomorrow. | ||||||
| 5. **Human centric**: The most valuable resource is the time of human maintainers. That must be used carefully. | ||||||
|
|
||||||
| These points can be summarized in a fundamental principle for OpenCloud in relation to AI: | ||||||
|
|
||||||
| >*OpenCloud is a project driven by responsible humans. We take a positive view on using AI as a tool to speed up and refine work. However, we expect that human work habits and processes are always respected. For every contribution a person is held accountable.* | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| Requirements are further specified below. Contributions that do not comply with this requirements will be rejected without further discussion. | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| ## Fit to the Project | ||||||
|
|
||||||
| Before submitting a PR to any repository of OpenCloud, think about it's size and fit to the project. That is a major factor on how careful the PR needs to be prepared and how maintainer look at it. | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| ### Bug Fixes | ||||||
| Bug fixes in form of "one-liners", typo fixes, fixes to translations and such are always very appreciated. Never think "that is too trivial to submit", it is not. | ||||||
|
|
||||||
| ### Refactorings | ||||||
| Bigger changes that fix misbehaviour, refactor parts of the codebase are also appreciated, but be careful. Have tests and keep changes small. Possibly talk before submitting what the maintainers think of your idea. | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| ### Feature Additions | ||||||
| Yes, we love it, but we also apply the rules here, as we take the responsibility to maintain code that we include into the project. Try to structure the changes you plan into multiple steps to make it easier to overlook. Try to consider alternatives and document your decisions (ADR). | ||||||
|
|
||||||
| Most important: make sure to talk before you invest work and tokens. There is a chance that we will not take your contribution even if it is formally great because it does not fit the roadmap. | ||||||
|
|
||||||
| ### "Scratch your itch" | ||||||
| "Scratching your own itch" and pushing the results upstream is in general a great motivation to contribute to open source projects. OpenCloud supports that idea. | ||||||
| However, we have to keep the main direction of the project in mind, so we can not accept every "special purpose" feature. | ||||||
|
|
||||||
| Make sure to find a ballance between functions that are good for everybody and your own needs. You will have to keep private patches for some of your additions. | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
Comment on lines
+36
to
+39
Member
There was a problem hiding this comment. Maybe worth adding a sentence about the web-extension framework as a way to add functionality without necessarily committing all of it upstream? |
||||||
|
|
||||||
| ## Pull Requests | ||||||
|
|
||||||
| Contributions to all parts of the project are very appreciated. To submit a contribution via Github Pull Requests, the following points need to be considered: | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| 1. YOU are responsible for what you submit, not your agent. Make sure you completely understand what you submit. Be able to answer questions. Be open about your way to use AI. | ||||||
| 2. Keep PRs short. The shorter the better, as that is easier for humans. Split code contributions to multiple PRs. Invest time in finding logical portions of bigger contributions and reference the PRs accordingly. | ||||||
| 3. Authorship is for humans, not tools. Code assistants and such should not be described in commits using tags like "Co-authored-by" or similar. Nor must they be listed as primary author. | ||||||
| 4. To be sensitive about others time, keep descriptions short and concise. Another person should understand your idea within tem seconds. Consider splitting your comments to a summary on top and detailed description below. | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
| 5. Check your contribution: Review your AI generated PR carefully before submitting it. Abstain from copy & paste. It is YOU who submits it, not an AI. Maintain your contributor reputation. | ||||||
| 6. Add useful comments, tests and documentation additions to your contribution. AI is a great help for that. | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| These rules are mostly soft. But maintainership considers to put hard limits behind some of them in the CI which results in automatic decline of PRs in Github. | ||||||
|
|
||||||
| ## Human interaction | ||||||
|
|
||||||
| OpenCloud is and will be a human driven project. Keep that in mind with every contribution and interaction. Beside a friendly and patient attitude, a human friendly style of communication and working is expected. | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| 1. Ask questions early. It is easier to answer a question that clarifies things than declining a PR that does not fit. | ||||||
| 2. Be responsive. If maintainers have questions, please be responsive. | ||||||
| 3. Be precise. Try to stick to the topic and answer questions carefully. | ||||||
| 4. Try to act sustainable: Bigger one-off contributions are of limited use. Taking responsibility to improve and maintain a contribution over time is very appreciated. | ||||||
|
|
||||||
| Please help us to refine these guidelines by submitting a PR. | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.