Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
53 lines (27 loc) · 4.43 KB

CONTRIBUTING.md

File metadata and controls

53 lines (27 loc) · 4.43 KB
Raw

Contributing to this repository

VERSION: 1.4

General Considerations

The master branch (representing Core targets) is periodically refreshed from main AROS repository. This means the more the master branch diverges, the more costly it is to bring back changes from main AROS repository. The divergence is unavoidable, however rules are set in place to keep it under control over time. Additionally rules are introduced to manage cooperation of different projects on repository itself.

Rules

Repository structure

  • Do not delete/move/rename files and directories without a very good reason. Doing so always causes conflicts when applying patches from main AROS repo. Always check with master branch maintainer before doing such changes.

  • Consider creating pull requests to AROS repository (https://github.com/aros-development-team/) for changes committed to this repository. This helps keep the divergence under control which is appreciated by master branch maintainer. This is not a hard requirement though.

  • Remember that there are alternatives based on master branch. Alternatives will try to limit the divergence with master branch by committing as much code as possible to master. This however can give impression that there is unused code in master branch. Always check alternatives before making any actions on such code.

  • Do not use sub-modules and external repository linking. Sub-modules make rebase flow and branch switching a more complex and error-prone operation. If you need external codes in the repository, check how to proceed with master branch maintainer.

PRs / Commits / Pushes

  • PRs vs commit + push. Changes to repository structure, ABI or public API or changes with far reaching effects (i.e. big update to frequently user library) go through PRs. All other can go through commit and push.

  • Describe 'why' along with 'what' in commit messages. Describing the reason behing the change, the seen and expected behavior, the bug condition etc. is an immense help to person in future reviewing a change and trying to understand why it is necessary.

  • Do not push with force (-f, --force). If git reports non forwardable changes, understand what caused this and fix the problem.

  • Avoid merging branches. Push changes directly to master rather then have branches merged. This keeps a clean and simple to understand repository history.

  • Pull changes with rebase (git pull --rebase) This way your changes are not merged, but put on top of already pushed commits, which makes it easier to understand repository history.

  • Separate formatting changes. If you are reformatting code, make it a separate commit so that formatting and actuall code changes are not mixed.

Code format

  • Use 4 spaces for indentation instead of tab. Different editors interpret tab differently which over time causes the code to become unreadable when multiple people work on it, each with different tab settings.

  • Match local opening braces style. Most files use opening braces on next line, which is the default. Some file use braces on same line. Match the style you find in function or file so that local code formatting remains consistent.

  • Use ISO-8859-15 file encoding for source code. Having same settings across different developers avoid unnecessary re-formating changes.

  • Limit line length to 120 characters for code and comments. Limit line length to 80 characters for autodocs. While 80 characters limits is no longer needed in 2020s, we are keeping it for backward compatibility with autodocs format which can be displayed on older hardware (Amigas).

  • Use D(bug(x)); form, not D(bug(x);) form for single line debug statements. The recommended form allows quick enabling of selected debug lines just by deleting the 'D' letter.

Use of AI tools and other tools

  • AI is just another tool. Use if it you like. If you use it, treat it as just another tool, not as an (legal) entity.

  • You are still the only author. Whatever tools you use to develop your code, you need to guarantee that you can explain in your own words what the code does, that the code was tested and that you claim the copyrights for that code. Clear, human ownership of copyrights is expected. Commits which mention tools as "co-authors" cannot be accepted.

  • Keep code comments clean of tool details. Code comments are meant to describe the expected behavior of code, not to document what tools were used to develop it.