diff --git a/docs/Contributing.md b/docs/Contributing.md index 1eaadd3..62b11da 100644 --- a/docs/Contributing.md +++ b/docs/Contributing.md @@ -11,3 +11,121 @@ your editor is taking note of those settings, or cross-check its contents with the [editorconfig documentation](https://github.com/editorconfig/editorconfig/wiki/EditorConfig-Properties) , and ensure your editor/IDE's settings match. + +## Code Changes + +### Bug Fixes + +### Enhancements + +## Adding a New Schema + +If you think you have a good case for an additional EDDN Schema then there are +several things you should consider: + +1. What is the source of the data? In almost all circumstances the only + acceptable sources are the game Journal files and the Frontier CAPI service. + We do *NOT* want manually entered data being sent over EDDN, it's too prone + to error. + +2. Is the new Schema going to be practically useful ? + 1. What use cases are there for the new data? + 2. Who benefits ? + 3. What's the likely volume of messages compared to existing Schemas? If + there would often be many messages in a short space of time consider + requiring senders to batch them. 2022-01-28: There's no live example of + this yet, but see + [discussion of adding support for FSSSignalDiscovered](https://github.com/EDCD/EDDN/issues/152) + . + 5. What's the likely size range of the new messages? The Gateway has a + limit on the size of the *body* of `/upload/` requests. Check + [live branch src/eddn/Gateway.py](https://github.com/EDCD/EDDN/blob/live/src/eddn/Gateway.py) + `bottle.BaseRequest.MEMFILE_MAX = ...` for the current limit. + +3. For CAPI-sourced data you need to keep in mind the possible synchronization + issues between it and any necessary data augmentations from Journal data. + This might mean needing to make such augmentations optional. + +4. For Journal-sourced data if the source is an event not yet allowed by any + existing Schema then you MUST define a wholly new Schema for the data. This + allows you to fully specify both required and forbidden information in the + resulting messages. + The Journal events that are handled in the generic `journal` Schema are only + there for historical reasons and due to the difficulties in ensuring all + listeners and senders migrate to separate Schemas in a synchronized manner. + +5. Ensure you read + [the general Schemas README](https://github.com/EDCD/EDDN/blob/live/schemas/README-EDDN-schemas.md) + so as to be aware of general requirements that your new Schema will need to + adhere to. + +7. You **MUST** + [open an issue on GitHub](https://github.com/EDCD/EDDN/issues/new) + in order to propose the new Schema. If a consensus appears to have been + reached in comments therein then start work on a Pull Request. + +8. There must be at least one working Sender implementation before the Pull + Request for a new Schema will be merged into the live service. Experience + has demonstrated that there are often caveats and gotchas discovered during + the development of a Sender for a new Schema. + Often this will end up being a Pull Request against either + [Elite Dangerous Market Connector](https://github.com/EDCD/EDMarketConnector) 's + EDDN plugin, or [ED Discovery](https://github.com/EDDiscovery/EDDiscovery). + +The Schema files are placed in the `schemas/` directory, located in the root +of the project structure. They are +[JSON](https://www.json.org/json-en.html) +files, conforming to the +[JSON Schema](https://json-schema.org/) +specification. As of 2022-01-28 we still use 'draft 04' of this specification. +We are looking into updating to the latest in +[#139 - Update to latest JSON schema version(s) ](https://github.com/EDCD/EDDN/issues/139). + +All Schema files MUST be accompanied by a MarkDown formatted README file. + +### Always start a new Schema at version 1 + +The first time a new Schema goes live it should be as version 1. + - What should policy be on incrementing the version ? I'm not confident + anything other than an integer is actually supported - Ath + +Any breaking changes **MUST** increment the version number. Use a git file +rename to update the name of the file. Examples of such breaking changes +include: + +- If you add a new required property. Senders will need to update. +- If you remove a required property *and making it optional doesn't make + sense*. Senders will need to update. Listeners will need to cope with the + data no longer being present. +- If you change a property from optional to required or disallowed. Senders + will need to update. Listeners can no longer expect it, if disallowed. + +### Necessary file edits + +1. Obviously you need to create the new file, in the `schemas/` directory. + This should be named as per the data source, i.e. Journal `event` value, and + include the Schema version, and `.json` extension. You **MUST** fold the + the `event` value to lower case for this. + An example is `fssdiscoveryscan-v1.0.json` for adding support for the Journal + `FSSDiscoveryScan` event. + +2. You **MUST** also create the README file for the new Schema. This is also + placed in the `schemas/` directory. The name should match that of the + Schema file itself, without the version, and with a `.md` extentions instead + of `.json`. + An example is `fssdiscoveryscan-README.md` documents the + `fssdiscoveryscan-v1.0.json` Schema file. + +3. You will need to add two lines to `src/eddn/conf/Settings.py` in order to + have the Gateway actually recognise the new Schema. You are adding to the + end of the `GATEWAY_JSON_SCHEMAS` dictionary. Both the live Schema *and* + the `/test` version **MUST** be added. + For `fssdiscoveryscan-v1.0.json` you would add: + ```python + + "https://eddn.edcd.io/schemas/fssdiscoveryscan/1" : "schemas/fssdiscoveryscan-v1.0.json", + "https://eddn.edcd.io/schemas/fssdiscoveryscan/1/test" : "schemas/fssdiscoveryscan-v1.0.json", + ``` + Please ensure you use the current hostname as per the entries for already + existing Schemas. Keep the trailing comma on the final entry, Python + allows it, and it will reduce the diff on adding any further Schemas.