[WIP] Add an AI Guideline for OpenCloud plus minor adjustments in README - #29
Open
dragotin wants to merge 2 commits into
Open
[WIP] Add an AI Guideline for OpenCloud plus minor adjustments in README#29dragotin wants to merge 2 commits into
dragotin wants to merge 2 commits into
Conversation
AlexAndBear
requested changes
Jul 24, 2026
| 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
| 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. | |
| Bigger changes that fix misbehaviour, refactor parts of the codebase are also appreciated, but be careful. Have tests and keep changes small. Possibly ask before submitting what the maintainers think of your idea. |
|
|
||
| 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
| 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. | |
| 1. **Code Quality**: OpenCloud has a strong focus on code quality as we know that dealing with user data comes with a great responsibility for data security. All contributions have to put that first. |
| 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. | ||
| 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
| 2. **Focus**: OpenCloud serves a certain purpose which is defined very carefully by product managenment. All contributions have to align with that roadmap. | |
| 2. **Focus**: OpenCloud serves a certain purpose which is defined very carefully by product management. All contributions have to align with that roadmap. |
|
|
||
| ## 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
| 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. | |
| Before submitting a PR to any repository of OpenCloud, think about its size and fit to the project. That is a major factor on how careful the PR needs to be prepared and how maintainers look at it. |
| "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
| 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. | |
| Make sure to find a balance between functions that are good for everybody and your own needs. You will have to keep private patches for some of your additions. |
|
|
||
| ## 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
| 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: | |
| 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: |
|
|
||
| ## 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
| 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. | |
| OpenCloud is and will be a human driven project. Keep that in mind with every contribution and interaction. Besides a friendly and patient attitude, a human friendly style of communication and working is expected. |
JammingBen
reviewed
Jul 24, 2026
| # 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. |
Member
There was a problem hiding this comment.
Suggested change
| This document will set up guidelines how we work with AI and how we ask contributors to work with it. | |
| This document sets up guidelines how we work with AI and how we ask contributors to work with it. |
|
|
||
| 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
| >*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.* | |
| >*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.* |
|
|
||
| >*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.* | ||
|
|
||
| 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
| Requirements are further specified below. Contributions that do not comply with this requirements will be rejected without further discussion. | |
| Requirements are further specified below. Contributions that do not comply with these requirements will be rejected without further discussion. |
Comment on lines
+36
to
+39
| "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.
Maybe worth adding a sentence about the web-extension framework as a way to add functionality without necessarily committing all of it upstream?
| 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
| 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. | |
| 4. To be sensitive about others time, keep descriptions short and concise. Another person should understand your idea within ten seconds. Consider splitting your comments to a summary on top and detailed description below. |
| 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. | ||
| 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
| 6. Add useful comments, tests and documentation additions to your contribution. AI is a great help for that. | |
| 6. Add useful comments, tests and documentation additions to your contribution. AI is a great help for that. |
pbleser-oc
reviewed
Jul 27, 2026
|
|
||
| # AI Contributions | ||
|
|
||
| AI usage is causing challenges for all open source projects, so for OpenCloud. |
Member
There was a problem hiding this comment.
Suggested change
| AI usage is causing challenges for all open source projects, so for OpenCloud. | |
| AI usage is causing challenges for all open source projects, and thus also for OpenCloud. |
pbleser-oc
reviewed
Jul 27, 2026
| # 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. |
Member
There was a problem hiding this comment.
Suggested change
| This document will set up guidelines how we work with AI and how we ask contributors to work with it. | |
| This document defines guidelines regarding how we work with AI and how we ask contributors to work with it. |
pbleser-oc
reviewed
Jul 27, 2026
| 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. | ||
| 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
| 2. **Focus**: OpenCloud serves a certain purpose which is defined very carefully by product managenment. All contributions have to align with that roadmap. | |
| 2. **Focus**: OpenCloud serves a specific purpose which is defined very carefully by product managenment. All contributions have to align with that roadmap. |
"specific" better hints at "well-defined", whereas "certain" is rather vague
pbleser-oc
reviewed
Jul 27, 2026
| 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. | ||
|
|
||
| ### 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). |
Member
There was a problem hiding this comment.
Suggested change
| 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). | |
| 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 understand and review. Try to consider alternatives and document your decisions (ADR). |
aduffeck
reviewed
Jul 27, 2026
| 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.
From my experience with agent generated PRs this is actually what I struggle most with besides the amount and quality of code itself. There's something about the way the agents often write the PR description that makes it really hard for me to parse and understand. They tend to be too long and verbose, mix important and much less relevant things, and just have a style that makes it hard for my brain to follow.
I'm not sure how to phrase it better or what kind of rule to apply here however, to be honest. The "keep it short and concise" kinda covers it already but I still feel like it might be a bit too weak. Maybe explicitly demanding a human-centric form and style would do the trick?
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
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.
This is a WIP of the AI guideline for the OpenCloud project.
Feel free to review and discuss.
Once we have a agreed version it will be linked from the organization main README.