diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000000000000000000000000000000000..a13956e2b4b6bcf78efe8423da25333a522aefc4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,73 @@ +# Contributing to Backbone Message Formats +_Last updated: 01 Dec 2022_ +<br/> + +Guidelines for our project partners to collaborate in this workspace specifically for message formats that interact with each partner's software components and the Communications Backbone. +<br/><br/> + +## Where To Find A Brief on Message Formats +Please refer to the [**README.md**](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/blob/master/README.md) file that summarises the `message types` and `message flows`. +> _Info: [Quick Links](#quick-links) might be helpful too!_ + +<br/> + +## Commenting +A great way to collaborate and refine the message formats is by commenting on the schema definitions/examples (within the code itself) or on an `issue` card. +### **Commenting on Code** +Go to [`Merge Requests`](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/merge_requests), add your comment and click `Add comment now`. Be sure to **tag partners** who should response. **Use `@`** followed by the **partner's username** or **tag a partner's** organisation by **adding a label**. + +P.S. The initial working branch is [`create-initial-message-formats`](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/merge_requests/2/diffs). + + **But _HOW_ Do I Add A Comment?** +> A. To **comment directly on the** [**`master` branch**](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/tree/master) directly, hover over the left column that shows the line numbers, and click on the **paperclip icon**. This copies the specific line of code. You can then proceed to pasting this link into a new issue as per [Raising New Ideas or Questions](#raising-new-ideas-or-questions). + +> B. To **comment on a Merge Request**, hover over the left column that shows the line numbers, and click on the _paperclip_ or _comment bubble_ icon. This copies the line of code. You can then proceed to pasting this link into a new issue as per [Raising New Ideas or Questions](#raising-new-ideas-or-questions). + +<br/> + +### **Commenting on Issue Cards** +Go to the [issue](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/issues), scroll to the bottom of the page and add your comment. Once done, click on `Comment`. +<br/><br/> + + +## Raising New Ideas or Questions +If you have an idea or a question for our collaborators, it's simple! [`Create a new issue`](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/issues/new?issue), assign a person to respond/take action under `Assignee`, and add a partner under `Labels` . +<br/><br/> + + +## Labels Summary +To add/edit labels, go to [manage labels](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/labels). +| Category | Labels Available | Description | +| -------- | ---------------------------------------------------------- | ----------------------------------------------------------------------- | +| Project | `SoAR` | Associated project | +| Partner | `Planet Ocean`, `Hydro-Surv`, `NOC`, `RHU` | Associated partner | +| Asset | `ah1`, `ecosub`, `reav`, `autonomy engine` | Associated vehicle | +| Status | `In Sprint Backlog`, `In Progress`, `In Review`, `BLOCKED` | Status of resolving issue | +| Weight | `0`, `1`, `2`, `3`, `5`, `8` | Complexity of issue (0 - quick task and 8 - full 2 weeks worth of work) | +| - | `bug`, `feature` | Type of issue i.e. new feature, bug | +<br/> + + +## Quick Links +1. [Schema Fields Definitions](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/tree/7-message-formats-initial/formats) +2. [JSON Schema Examples](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/tree/7-message-formats-initial/examples) + +### Project-Specific: SoAR Project +* **[Reference SoAR Message Format Slides](https://planetocean15.sharepoint.com/sites/IUKSoAR/Shared%20Documents/Forms/AllItems.aspx?id=%2Fsites%2FIUKSoAR%2FShared%20Documents%2FTechnical%2FTechnical%20meetings%2FDiscussions%E2%80%94%20Backbone%20Message%20Formats%2Epdf&viewid=1d649f5f%2Dd30e%2D482f%2Dbd77%2D9316a0023bf9&parent=%2Fsites%2FIUKSoAR%2FShared%20Documents%2FTechnical%2FTechnical%20meetings)** +* To view schema docs via Swagger UI, run the command below and go to `http://127.0.0.1:5000` + ``` + python3 docs/generate_swagger.py + ``` + *Disclaimer: These are *not* endpoints. Purely for schema representation purposes. + > TEMPORARY: Pregenerated Swagger docs can be [viewed here](https://planetocean15.sharepoint.com/sites/IUKSoAR/Shared%20Documents/Forms/AllItems.aspx?id=%2Fsites%2FIUKSoAR%2FShared%20Documents%2FTechnical%2FTechnical%20meetings%2Finitial%2Dswagger%2Ddocs%2Ddraft%2Epdf&viewid=1d649f5f%2Dd30e%2D482f%2Dbd77%2D9316a0023bf9&parent=%2Fsites%2FIUKSoAR%2FShared%20Documents%2FTechnical%2FTechnical%20meetings). + +<br/> + + +## Getting Started +> Notes for this section is in PROGRESS +1. Clone this gitlab repository: +``` +git clone https://git.noc.ac.uk/communications-backbone-system/backbone-message-format.git +``` +2. Install the dependencies from `requirements.txt`. \ No newline at end of file diff --git a/README.md b/README.md index 24f1f34e75c081e74c204fdf4ba8b49dd82523a0..6ef61cb78686d0a246cc7099205833788a540d9f 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@ # Overview This project repository is a collaborative workspace. It consists of all messages transferred into and out of the Communications Backbone. Message type schemas will be developed once reviewing each vehicle's data and statuses defined by each partner. -**[Reference Slides](https://planetocean15.sharepoint.com/sites/IUKSoAR/Shared%20Documents/Forms/AllItems.aspx?id=%2Fsites%2FIUKSoAR%2FShared%20Documents%2FTechnical%2FTechnical%20meetings%2FDiscussions%E2%80%94%20Backbone%20Message%20Formats%2Epdf&viewid=1d649f5f%2Dd30e%2D482f%2Dbd77%2D9316a0023bf9&parent=%2Fsites%2FIUKSoAR%2FShared%20Documents%2FTechnical%2FTechnical%20meetings)** - # Message Types @@ -19,83 +17,6 @@ This project repository is a collaborative workspace. It consists of all message | `acknowledgement` | Decoded/de-serialized acknowledgement message from the Hydrosurv Adapater | No | ----------------------------------- - - -## Breakdown of Message Sources & Types -### 1/ Autonomy Engine -#### Transmit -* mission plan _(sent per vehicle??)_ -* TBD: - * Will emergency commands be sent via the autonomy engine (from the GUI) or directly to the C2s? - -#### Receive -* configuration file -* emergency stop all -* decoded ecosub status message -* decoded reav status message -* decoded autosub-hover status message -* decoded ecosub observation data _(from squad 1 vehicles)_ - ----------------------------------- - -### 2/ Ecosub C2 -#### Transmit -* compiled ecosub mission plan -* decoded ecosub status message -* autonomy configuration file -* decoded ecosub observation data - - -#### Receive -* mission plan -* encoded ecosub status message -* encoded ecosub observation data - ----------------------------------- - -### 3/ Autosub C2 -#### Transmit -* compiled autosub-hover mission plan -* decoded autosub-hover status message -* autonomy configuration file - - -#### Receive -* mission plan -* encoded autosub-hover status message - - ----------------------------------- - -### 4/ Reav C2 -#### Transmit -* decoded reav-60 status message? - - -#### Receive -* mission plan -* encoded reav-60 status message? - ----------------------------------- - -### 5/ Hermes Box/Hydrosurv Smart Router? -#### Transmit -* encoded ecosub status message -* encoded (or is this already decoded?) reav status message -* encoded autosub status message -* encoded ecosub observation data -* TBD: - * are there acknowledgment messages from vehicles? - * how are we receiving beacon messages per vehicle? - -#### Receive -* compiled ecosub mission plan -* compiled reav mission plan -* compiled autosub mission plan -* compiled ecosub emergency command -* compiled reav emergency command -* compiled autosub emergency command ------------------------------------- ## Message Data Flow Summary | Partner | Message Type | Source | Destination | Via Comms Backbone? | Contains Serialized Vehicle-Specific File? | Comment | | --------------- | ---------------------- | ----------------- | ---------------------- | ------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------- |