Skip to content

Latest commit

 

History

History
143 lines (110 loc) · 6.39 KB

CONTRIBUTING.rst

File metadata and controls

143 lines (110 loc) · 6.39 KB
Raw

Reporting Issues/Bugs

Thanks for reporting issues to ARTIQ! You can also discuss issues and ask questions on IRC (the #m-labs channel on OFTC), the Mattermost chat, or in the forum.

The best bug reports are those which contain sufficient information. With accurate and comprehensive context, an issue can be resolved quickly and efficiently. Please consider adding the following data to your issue report if possible:

  • A clear and unique summary that fits into one line. Check that this issue has not yet been reported; if it has, add additional information there.
  • Precise steps to reproduce (a list of actions that leads to the issue)
  • Expected behavior (what should happen)
  • Actual behavior (what happens instead)
  • Logging message, tracebacks, screenshots, where applicable
  • Components involved (omit irrelevant parts):
    • Operating system used
    • ARTIQ version (run any command in the form of artiq_client --version)
    • Gateware and firmware loaded to the core device (in the output of artiq_coremgmt [-D ....] log)
    • Hardware involved

For in-depth information on bug reporting, see:

http://www.chiark.greenend.org.uk/~sgtatham/bugs.html https://developer.mozilla.org/en-US/docs/Mozilla/QA/Bug_writing_guidelines

Contributing Code

ARTIQ welcomes contributions. Write bite-size patches that can stand alone, clean them up, write proper commit messages, add docstrings and unit tests; git rebase them onto the current master or merge the current master. Verify that the test suite passes. Then submit a pull request. Expect your contribution to be held up to coding standards (e.g. use flake8 to check yourself).

Checklist for Code Contributions

  • Test your changes or have someone test them. Mention what was tested and how.
  • Use correct spelling and grammar. Use your code editor to help you with syntax, spelling, and style
  • Style: PEP-8 (flake8)
  • Add or update docstrings and comments
  • Split your contribution into logically separate changes (git rebase --interactive). Merge (squash, fixup) commits that just fix previous commits or amend them. Remove unintended changes. Clean up your commits.
  • Check the copyright situation of your changes and sign off your patches (git commit --signoff, see also below)
  • Write meaningful commit messages containing the area of the change and a concise description (50 characters or less) in the first line. Describe everything else in the long explanation.
  • Review each of your commits for the above items (git show)
  • Update RELEASE_NOTES.md if there are noteworthy changes, especially if there are changes to existing APIs
  • Check, test, and update the documentation in doc/
  • Check, test, and update the unit tests
  • Close and/or update issues

Contributing Documentation

ARTIQ welcomes documentation contributions. The ARTIQ manual is hosted online in HTML form here and in PDF form here. It is generated from source files in doc/manual, written in a variant of the reStructured Text markup language processed by Sphinx, with some of the additional reference material processed from inline documentation in the ARTIQ source itself.

Write bite-size patches that can stand alone, clean them up, write proper commit messages. Check that your edits render properly and compile without errors:

$ nix build .#artiq-manual-pdf
$ nix build .#artiq-manual-html

Elaborations, improvements, clarifications and corrections to any of the material are happily accepted, but special attention is drawn to the manual FAQ, where tips and solutions are especially easy to add. See also the FAQ's own section on the subject.

Copyright and Sign-Off

Authors retain copyright of their contributions to ARTIQ, but whenever possible should use the GNU LGPL version 3 license for them to be merged.

Works of US government employees are not copyrighted but can also be merged.

We've introduced a "sign-off" procedure on patches that are being sent around.

The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as an open-source patch. The rules are pretty simple: if you can certify the below:

Developer's Certificate of Origin (1.1 from the Linux kernel)

By making a contribution to this project, I certify that:

  1. The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or
  2. The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or
  3. The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.
  4. I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.

then add a line saying

Signed-off-by: Random J Developer <[email protected]>

using your legal name (sorry, no pseudonyms or anonymous contributions.)

ARTIQ files that do not contain a license header are copyrighted by M-Labs Limited and are licensed under GNU LGPL version 3 or later.