diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..8ab5f58 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,134 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic +status, nationality, personal appearance, race, caste, color, religion, or +sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances + of any kind +* Trolling, insulting or derogatory comments, and personal or political + attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards +of acceptable behavior and will take appropriate and fair corrective action +in response to any behavior that they deem inappropriate, threatening, +offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, and will communicate reasons +for moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies +when an individual is officially representing the community in public +spaces. Examples of representing our community include using an official +e-mail address, posting via an official social media account, or acting as +an appointed representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +rc-ssl-oc@lists.robocup.org. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of +the reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in +determining the consequences for any action they deem in violation of this +Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, +providing clarity around the nature of the violation and an explanation of +why the behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public +or private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during this +period. Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available +at [https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ba0e08f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,131 @@ +# Contributing Guide + +This document provide guidelines for contributing to this repository. + +## Scope + +Any high-level documentation related to the SSL is welcome here. This includes anything not clearly having a home +elsewhere. + +Architecture documentation is welcome here. This may include items such as fields, protocols, league technical +summaries, or community technical surveys of TDPs or other academic publications. + +In general, development specific documentation for league tools should live with that tool. This includes detailed +descriptions of commands, dependencies, bugs, etc. Consider opening issues or pull requests on those tools when +issue arise. However, higher level documentation is very welcome here. This would include step-by-step usage guides, +guides that include the tools in broader application, e.g. an example of calibrating vision to a specific field. When, +possible, documentation should not be duplicated from a league tool repository. It's expected though that a usage guide +may invoke some of the documented commands or compile steps. Consider adding an external link for the full +documentation and just invoking the command here. + +If a league or external tool defines a _formal contract_ for usage, the definition of that contract must be +unambiguous. For example, the league [protocol definitions repository](https://github.com/RoboCup-SSL/ssl-protocol-defs) +is the authoritative source on the data format of the protocols. However some aspects of the protocol outside the data +format are defined here, such as standard port numbers and expected network topology. On pages of this nature the +author _must_ clearly separate what is defined where and link to external resources. Consider opening an Issue with +the "discussion" tag if you are unclear about a boundary; a committee member can quickly help set the boundary of what +should be documented where. + +## Style + +Pages should be written in clear concise technical English. Avoid abbreviations and sentence fragments in wiki pages. +Do not use overly flowery language or sentence enhancers. Reviewers **will** request language be tightened if this +writing stype is present. + +Use figures to augment or replace prose when possible. This improves readability. In order of preference, add +images as [SVG](https://en.wikipedia.org/wiki/SVG), then PNG, then JPG. This instance supports native rendering of +[Mermaid Diagrams](https://en.wikipedia.org/wiki/Mermaid_(software)) and +[Diagrams.net (draw.io)](https://en.wikipedia.org/wiki/Diagrams.net). Care has been taken to support both light and +dark rendering for both options, though rendering draw.io is slightly more complicated due to limitations with the +sphinx supporting module. Use Mermaid if possible. + +For algorithms or calculations, considering embedded a JavaScript asset. See the Camera Calculator page as an +example. + +### Adding Images + +Add images with following block: + +```` +![Image Name](../images/image1.svg) +```` + +The name on the left is used when the asset cannot be loaded. Use relative paths to reference the image. Images live +in an `images/` subfolder next to the page that uses them. Save and commit your images there. + +### Adding Mermaid Diagrams + +Mermaid sources live as `.mmd` files in a `diagrams/` subdirectory next to the page that uses them, and are +embedded with the `mermaid` directive: + +```` +```{mermaid} diagrams/my-diagram.mmd +``` +```` + +Mermaid renders natively in both light and dark themes. + +### Adding Diagrams.net + +Diagrams.net (draw.io) sources live in a `diagrams/` subdirectory next to the page that uses them. Draw the +diagram with the [desktop app or diagrams.net](https://www.diagrams.net/) and save the `.drawio` file there. + +Diagrams are pre-rendered at build time into separate light and dark SVGs so they track the site's theme toggle +correctly. To wire up a new diagram, add its path to `DUAL_THEME_DIAGRAMS` in [`conf.py`](docs-source/conf.py): + +```python +DUAL_THEME_DIAGRAMS = [ + "field/network/diagrams/ssl_field_network_fanout_truss.drawio", + "field/network/diagrams/ssl_field_network_fanout_direct.drawio", + "field/network/diagrams/my_new_diagram.drawio", # new entry +] +``` + +Then reference the generated `.light.svg` / `.dark.svg` pair with Furo's theme-scoped image classes: + +```` +```{image} diagrams/my_new_diagram.light.svg +:class: only-light +:alt: Description of the diagram +``` + +```{image} diagrams/my_new_diagram.dark.svg +:class: only-dark +:alt: Description of the diagram +``` +```` + +Building the docs (inside `nix develop`) regenerates the two SVGs from the `.drawio` source automatically. The +generated svg files should not be committed to git and are ignored by the top-level .gitignore file by default. + +## Opening Issues + +Feel free to open issues to raise bugs, request new pages, or discuss the reorganization or migration of existing +documentation. Take a look at the `type` labels and be sure to assign the right one. Please open a discussion issue +if you expect to make a large contribution or otherwise thing the community might want to weigh in, including +dividing up work or setting scope. + +## Opening PRs + +Contributions are made though pull requests. If your PR addressing one or more issues, please tag them in in the +description. + +**PRs Must Include an AI Disclosure!** Please briefly describe what, if anything, AI assisted with. + +## Usage of AI + +Usage of AI is generally encouraged. The documentation maintainers strongly prefer pictures, graphics, diagrams, +and interactive webpages to static prose. AI is a powerful tool to improve visual communication. Use of AI is also +a powerful tool for language translation and improving technical brevity. + +**The author is responsible for the output of their AI.** We expect authors to check generated content for accuracy. +The AI must maintain a concise neutral or slightly friendly tone. Aggressive critical tone of in-league resources is +discouraged as is overly sycophantic or flattering language. Do not generate large amounts of text. This is technical +documentation designed primarily for utility. + +### Improving Language Density + +The following prompt is an example of guidance that can be given to an AI helping you write prose: + +> Use simple technical english. Do not use abbreviations, but standard acronyms are acceptable. Do not use sentence +> fragments. Strip or rewrite any casual and non-technical prose to emphasize readabilty of technical documentation. \ No newline at end of file diff --git a/README.md b/README.md index aec728e..ae8bb33 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,11 @@ # SSL Docs [**Live docs → robocup-ssl.github.io/ssl-docs**](https://robocup-ssl.github.io/ssl-docs/) - [![Build and deploy docs](https://github.com/RoboCup-SSL/ssl-docs/actions/workflows/docs.yml/badge.svg)](https://github.com/RoboCup-SSL/ssl-docs/actions/workflows/docs.yml) [![License: CC BY 4.0](https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg)](LICENSE) +See the [Contributing Guide](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md)! + RoboCup Small Size League docs. [Sphinx](https://www.sphinx-doc.org/) + [MyST](https://myst-parser.readthedocs.io/), deployed to GitHub Pages via Actions. This repository documents top level items, such as field architecture, new team guides, etc. Highly technical documentation regarding the usage of a