From ccf4dda28ddeb9ef4dfefaddc7bfa1e834b9b375 Mon Sep 17 00:00:00 2001 From: Federico Lolli <federico.lolli@skywarder.eu> Date: Mon, 11 Nov 2024 17:56:39 +0100 Subject: [PATCH] Updated README and added CONTRIBUTING and GLOSSARY --- CONTRIBUTING.md | 83 ++++++++++++++++++++++++++++ GLOSSARY.md | 5 ++ README.md | 144 ++++++++++++++++++++++++------------------------ 3 files changed, 160 insertions(+), 72 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 GLOSSARY.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..62f24fc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,83 @@ +# Contributing + +First off, thanks for taking the time to contribute! â¤ï¸ + +All types of contributions are encouraged and valued. See the [Table of Contents](#table-of-contents) for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. + +**Table of Contents** + +- [Contributing](#contributing) + - [I Want To Contribute](#i-want-to-contribute) + - [Reporting Bugs](#reporting-bugs) + - [Before Submitting a Bug Report](#before-submitting-a-bug-report) + - [How Do I Submit a Good Bug Report?](#how-do-i-submit-a-good-bug-report) + - [Suggesting Enhancements](#suggesting-enhancements) + - [Before Submitting an Enhancement](#before-submitting-an-enhancement) + - [How Do I Submit a Good Enhancement Suggestion?](#how-do-i-submit-a-good-enhancement-suggestion) + +<!-- ## I Have a Question + +> If you want to ask a question, we assume that you have read the available [Documentation](). + +Before you ask a question, it is best to search for existing [Issues](/issues) that might help you. In case you have found a suitable issue and still need clarification, you can write your question in this issue. It is also advisable to search the internet for answers first. + +If you then still feel the need to ask a question and need clarification, we recommend the following: + +- Open an [Issue](/issues/new). +- Provide as much context as you can about what you're running into. +- Provide project and platform versions (nodejs, npm, etc), depending on what seems relevant. + +We will then take care of the issue as soon as possible. --> + +## I Want To Contribute + +### Reporting Bugs + +#### Before Submitting a Bug Report + +A good bug report shouldn't leave others needing to chase you up for more information. Therefore, we ask you to investigate carefully, collect information and describe the issue in detail in your report. Please complete the following steps in advance to help us fix any potential bug as fast as possible. + +- Make sure that you are using the latest version. +- Determine if your bug is really a bug and not an error on your side e.g. using incompatible environment components/versions (Make sure that you have read the [documentation](). If you are looking for support, you might want to check [this section](#i-have-a-question)). +- To see if other users have experienced (and potentially already solved) the same issue you are having, check if there is not already a bug report existing for your bug or error in the [bug tracker](issues?q=label%3Abug). +- Collect information about the bug: + - Stack trace (Traceback) if any + - OS, Platform and Version (Windows, Linux, macOS, x86, ARM) + - Logs, if available + - Possibly your input and the output +- Can you reliably reproduce the issue? And can you also reproduce it with older versions? + + +#### How Do I Submit a Good Bug Report? + +We use GitHub issues to track bugs and errors. If you run into an issue with the project: + +- Open an [Issue](/issues/new). (Since we can't be sure at this point whether it is a bug or not, we ask you not to talk about a bug yet and not to label the issue.) +- Explain the behavior you would expect and the actual behavior. +- Please provide as much context as possible and describe the *reproduction steps* that someone else can follow to recreate the issue on their own. This usually includes your code. For good bug reports you should isolate the problem and create a reduced test case. +- Provide the information you collected in the previous section. + +Once it's filed: + +- The project team will label the issue accordingly. +- A team member will try to reproduce the issue with your provided steps. If there are no reproduction steps or no obvious way to reproduce the issue, the team will ask you for those steps and mark the issue as `needs-repro`. Bugs with the `needs-repro` tag will not be addressed until they are reproduced. +- If the team is able to reproduce the issue, it will be marked `needs-fix`, as well as possibly other tags (such as `critical`), and the issue will be left to be [implemented by someone](#your-first-code-contribution). + +### Suggesting Enhancements + +#### Before Submitting an Enhancement + +- Make sure that you are using the latest version. +- Read the [documentation]() carefully and find out if the functionality is already covered, maybe by an individual configuration. +- Perform a [search](/issues) to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one. +- Find out whether your idea fits with the scope and aims of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. Keep in mind that we want features that will be useful to the majority of our users and not just a small subset. If you're just targeting a minority of users, consider writing an add-on/plugin library. + +#### How Do I Submit a Good Enhancement Suggestion? + +Enhancement suggestions are tracked as [GitHub issues](/issues). + +- Use a **clear and descriptive title** for the issue to identify the suggestion. +- Provide a **step-by-step description of the suggested enhancement** in as many details as possible. +- **Describe the current behavior** and **explain which behavior you expected to see instead** and why. At this point you can also tell which alternatives do not work for you. +- You may want to **include screenshots and animated GIFs** which help you demonstrate the steps or point out the part which the suggestion is related to. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) or [this tool](https://github.com/GNOME/byzanz) on Linux. +- **Explain why this enhancement would be useful** to most CONTRIBUTING.md users. You may also want to point out the other projects that solved it better and which could serve as inspiration. diff --git a/GLOSSARY.md b/GLOSSARY.md new file mode 100644 index 0000000..d2ccf00 --- /dev/null +++ b/GLOSSARY.md @@ -0,0 +1,5 @@ +- **GS**: Ground Station, refers to the entire ground station system as a whole. +- **GSS**: Ground Station Software, refers to the ground station application software that runs on a personal computer. +- **GSB**: Ground Station Board. +- **Widget**: the smallest indivisible element that makes up the user interface. It is often identified with the term component in other contexts/languages. It features its own configuration independent of other widgets and operates independently. E.g., 2D/3D graphs, state machine visualizers, component health visualizers, raw message visualizers. +- **WRA**: without recompiling the application diff --git a/README.md b/README.md index f65ccbe..8f098a5 100644 --- a/README.md +++ b/README.md @@ -1,93 +1,93 @@ -# Skyward Enhanced Ground Station +<center> + <img src="./assets/logo.png" alt="Logo" width="200"/> + <h1>Skyward Enhanced Ground Station</h1> + <img src="https://img.shields.io/badge/version-v0.1.0-blue.svg?logo=rust"> + <img src="https://img.shields.io/badge/development-alpha-red"> +</center> +<br> -## Getting started +Skyward Enhanced Ground Station (in short **SEGS**) is a team effort that aims to provide a renewed and enhanced ground station experience for our operators. It is currently in development and is not ready for production use, contributions are welcome. -To make it easy for you to get started with GitLab, here's a list of recommended next steps. -Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)! +--- -## Add your files +**Table of contents**: +- [Installation](#installation) +- [Contributing](#contributing) +- [Roadmap](#roadmap) +- [Functional Requirements](#functional-requirements) -- [ ] [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files -- [ ] [Add files using the command line](https://docs.gitlab.com/ee/gitlab-basics/add-file.html#add-a-file-using-the-command-line) or push an existing Git repository with the following command: +--- -``` -cd existing_repo -git remote add origin https://git.skywarder.eu/avn/swd/segs.git -git branch -M main -git push -uf origin main -``` - -## Integrate with your tools - -- [ ] [Set up project integrations](https://git.skywarder.eu/avn/swd/segs/-/settings/integrations) - -## Collaborate with your team - -- [ ] [Invite team members and collaborators](https://docs.gitlab.com/ee/user/project/members/) -- [ ] [Create a new merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html) -- [ ] [Automatically close issues from merge requests](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically) -- [ ] [Enable merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/) -- [ ] [Set auto-merge](https://docs.gitlab.com/ee/user/project/merge_requests/merge_when_pipeline_succeeds.html) - -## Test and Deploy - -Use the built-in continuous integration in GitLab. - -- [ ] [Get started with GitLab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/index.html) -- [ ] [Analyze your code for known vulnerabilities with Static Application Security Testing (SAST)](https://docs.gitlab.com/ee/user/application_security/sast/) -- [ ] [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/requirements.html) -- [ ] [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/ee/user/clusters/agent/) -- [ ] [Set up protected environments](https://docs.gitlab.com/ee/ci/environments/protected_environments.html) - -*** - -# Editing this README - -When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thanks to [makeareadme.com](https://www.makeareadme.com/) for this template. - -## Suggestions for a good README - -Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information. +## Installation -## Name -Choose a self-explaining name for your project. +Since we are in the early stages of development, we do not provide a binary release yet. However, you can build the project from source. -## Description -Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors. +<!-- TODO: ADD BINARY RELEASE CI TASK --> -## Badges -On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge. +<!-- TODO: ADD USAGE SECTION ONCE WE REACH BETA --> -## Visuals -Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method. +<!-- TODO: UNCOMMENT THE FOLLOWING ONCE WE REACH BETA --> -## Installation -Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection. +<!-- ## Support -## Usage -Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README. +You can reach out to the project team for support, either through the issue tracker or the slack channel (`#segs-support`). --> -## Support -Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc. - -## Roadmap -If you have ideas for releases in the future, it is a good idea to list them in the README. +<!-- TODO: CREATE segs-support chnnale --> ## Contributing -State if you are open to contributions and what your requirements are for accepting them. -For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self. +If you want to contribute to the project, you can read the [CONTRIBUTING.md](./CONTRIBUTING.md) file for more information. -You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser. -## Authors and acknowledgment -Show your appreciation to those who have contributed to the project. - -## License -For open source projects, say how it is licensed. +## Roadmap -## Project status -If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers. +- [ ] **v0.1.0**: Alpha release, minimal features and layout to test the architecture in a real-world scenario. + - [ ] All Modularity requirements (R01, R01.1, R01.2, R02, R03) should be met + - [ ] Persistency R04 and R04.2 should be met + - [ ] ... (more to be defined) + + +## Functional Requirements + +In this section we refer to the precise wording defined in [RFC2119 IETF](https://www.ietf.org/rfc/rfc2119.txt) for the requirements. Additional terminology is defined in the [Glossary](./GLOSSARY.md). + +- [ ] **Modularity** + - [ ] **R01**: It **MUST** be fully modular: the layout (set of widgets) must be configurable *WRA* according to individual needs. + - [ ] **R01.1**: It **MAY** be implemented as a Tiling Manager with vertical and horizontal splitters to facilitate the migration from SkywardHub + - [ ] **R01.2**: It **MUST** support multiple windows: you must be able to split the layout into multiple distinct windows + - [ ] **R02**: The content displayed by the widgets **MUST** be configurable *WRA*. + - [ ] **R03**: The data source of the widgets' content **MUST** be configurable *WRA*. +- [ ] **Persistency and configuration management** + - [ ] **R04**: It **MUST** allow exporting and importing layout configurations in a serialized format: the entire layout must be serializable to a file (in JSON, XML, YAML, or any other format) to save, manage and load different configurations without needing to reset the system each time. + - [ ] **R04.1**: The serialization format **SHOULD** be easily interpreted by a human (human-friendly). + - [ ] **R04.2**: The serialization format **SHOULD** be uniquely tied to the Layout, in a declarative manner (the layout can be expressed and composed directly by using this format). +- [ ] **Data Sources configurability** + - [ ] **R05**: It **MUST** be able to receive Mavlink messages from one or more Serial and UDP connections. + - [ ] **R05.1**: It **MAY** provide auto detection of GSBs connected to the same LAN of a specific network card + - [ ] **R05.2**: It **MAY** provide filtering of serial ports showing only GSBs. + - [ ] **R05.3**: It **MUST** allow to manually specify which UDP socket/serial port to use for a connection +- [ ] **Widget requirements** + - [ ] **R06**: It **MUST** provide a widget for visualizing arbitrary fields from raw Mavlink messages in a textual format. + - [ ] **R07**: It **MUST** provide a plotting widget (both 2D and 3D). + - [ ] **R07.1**: It **MUST** be adjustable in terms of colors, scales and series to plot *WRA*. + - [ ] **R08**: It **MAY** provide a map widget (where the satellite map is displayed). + - [ ] **R09**: It **MUST** provide a state visualizer widget. + - [ ] **R09.1**: It **SHOULD** be completely configurable by the user *WRA*. + - [ ] **R10**: It **MUST** provide a widget displaying outgoing tele-commands and their corresponding reply in an organized manner. + - [ ] **R10.1**: It **MAY** provide an easy way to inspect previously sent tele-commands and their reply. + - [ ] **R11**: Every widget **SHOULD** display the time elapsed since its data source was last updated (aka. last reception of a message). + - [ ] **R12**: It **MAY** provide a timer widget (e.g. a countdown timer). + - [ ] **R13**: It **MUST** provide a widget capable of sending Mavlink commands with and without parameters (replacing legacy Command Pads and Compact Command Pads). + - [ ] **R13.1**: It **SHOULD** provide a setting to send the command periodically +- [ ] **User Interface and Interaction** + - [ ] **R14**: It **MUST** support light and dark color themes. + - [ ] **R14.1**: t **MAY** support other user-configurable themes *WRA*. + - [ ] **R15**: It **MUST NOT** send commands without the user's will (recognition of patterns and response with request of more information or sending of commands is not allowed). + - [ ] **R16**: It **SHOULD** account for different sizes of the monitor (responsive design) +- [ ] **Reproducibility** + - [ ] **R17**: It **MAY** provide a way to replay a stream of Mavlink messages from a file for testing. + - [ ] **R18**: It **SHOULD** log all received messages since the application started in a persistent manner. + - [ ] **R18.1**: It **MAY** directly decode the message. -- GitLab