Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
95 lines (74 loc) · 3.62 KB

CONTRIBUTING.md

File metadata and controls

95 lines (74 loc) · 3.62 KB

Thank you for contributing to SwissRETS

Repository directory index

  • docs Human readable documentation of the SwissRETS JSON schema
  • examples SwissRETS JSON example files
  • schema SwissRETS JSON schema files
  • scripts SwissRETS JSON schema files
  • scripts Script files
  • src Source files
    • ts Typescript source files
      • model Typescript model source files generated from the schema file
      • tests Typescript tests, mainly for the validator.
      • vaiidator Typescript schema validator.

Submitting a change request or an idea

  1. Go to the new issue page
  2. Make sure you fill only a single topic per issue
  3. Choose your template
  4. Please use english
  5. Submit

Pull request process

  1. Ensure all your changes follow the principles and rules of this document.
  2. Generate the typescript model and the html documentation from the json-schema (see above).
  3. Ensure eslint validation with pnpm run lint.
  4. Ensure all tests are green with pnpm run test.
  5. Push your branch and create a pull request.
  6. A maintainer will then take care about merging the pull request.

Release process (maintainer only)

  1. Execute the 'Release' action. A Github (pre-)release and npm package will automatically be created by the process.

Developing - before you start

You're very welcome to fork the project and send pull requests.

  1. Use an editor that supports ESLint.
  2. Install Node 22.14.0
  3. Fork the project - hit the Fork button on qualipool/swissrets-json - top right corner
  4. Clone your fork locally
  5. pnpm install
  6. Execute sudo chmod +x ./scripts/setup.sh.
  7. Execute ./scripts/setup.sh to install the required Python tooling and make generate-typescript-model.sh executable.

The schema file is the master for the model and documentation files. Do not edit the files under src/ts/model or docs directly, but use the respective generators to generate them.

Generating the typescript model from the json-schema

  1. Open a shell in the project root.
  2. Execute ./scripts/generate-typescript-model.sh to generate the model.

Generating the html documentation from the json-schema

  1. Open a shell in the project root.
  2. Execute generate-schema-doc schema/swissRetsSchema.json docs/index.html to generate the model.

Coding priciples

Mainly targeting the ./schema/schema.json

While we strive for all three, if we have conflicts, this list acts as priorities.

  1. Consistency
  2. Cleanness
  3. Ease of use

Consistency

SwissRETS is predictable.

  • Always solve the same things the same way
  • Have clear naming rules (TODO: add link)
  • Take time to refactor inconsistencies

Cleanness

SwissRETS is tidy and clean

  • Use real english words to name things
  • No abbrevations
  • Proper indentation (4 spaces)
  • Use syntax checks

Ease of use

SwissRETS is easy to use

  • We try to have as little documentation as necessary
  • Try to write selfspeaking code, to avoid documentation

Naming things

-> schema/swissRetsSchema.json

General naming rules

  • use real english words
  • for node and attribute names use camelCase
  • for attribute values use 'dash-separated-lower-case-words'
  • use a top-down naming schema, start with the broadest thing first and become more specific after
    • good: entryHallHeight, baths
    • bad: heightOfEntryHall, numberOfBaths