third-party-mirrors/EDDN
1
0
Fork 0
mirror of https://github.com/EDCD/EDDN.git synced 2025-04-18 09:37:38 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity
EDDN/docs/Contributing.md

6.1 KiB
Raw Blame History

Contributing to the EDDN Project

Introduction

This file is still mostly a stub.

Text format

The project contains an .editorconfig file at its root. Please either ensure your editor is taking note of those settings, or cross-check its contents with the editorconfig documentation , 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 .
    4. 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 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 so as to be aware of general requirements that your new Schema will need to adhere to.

  6. You MUST open an issue on GitHub 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.

  7. 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 's EDDN plugin, or ED Discovery.

The Schema files are placed in the schemas/ directory, located in the root of the project structure. They are JSON files, conforming to the JSON Schema 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) .

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:

    
    "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.