Contributing Guide

Thank you for investing your time in contribution to the dokieli project!

The dokieli/dokieli repository contains the source code of the work on dokieli project.

Dive into contributing

• Use it. Break it. Report it. Fix it.
• Improve documentation (for the website or repository)
• Publish or translate articles and share them. Add yours to the examples in the wild.
• Join the dokieli chat for help and discussion.
• Encourage the ideas/movement and however else you want to contribute.
• We want your feedback! Create issues (or PRs!) for use cases or features or you would like to have.

Code of conduct

We have a Code of Conduct to help keep our community inclusive, welcoming, and friendly.

See additional resources for education and training to promote a positive work environment.

Licensing

Contributions are made in a personal capacity. By contributing, you represent that you have the right to submit the work under:

• Source code is licensed under the Apache License, Version 2.0.
• Unless otherwise noted, resources such as images and other media assets are licensed under the Creative Commons Attribution 4.0 International.

Quality Assurance

dokieli follows a set of quality assurance principles to ensure code, translations, accessibility, and security meet expectations.

Code: There is documentation for tests and code quality. Code contributions are expected to be ultimately authored by humans, even if automated tools assist.

Internationalization: Dokieli suports internationalization and localization in order to make the user interface accessible in different languages. We welcome contributions to improve existing translations or add new languages. You can contribute translations via Weblate, or submit changes directly through Github.

Accessibility: dokieli has undergone an external accessibility review and uses automated accessibility tests (see tests) to help ensure the interface remains inclusive and usable.

Security: Dokieli has a Security Policy.

Standards: Dokieli is committed to implementing recognised web standards and best practises.

Development

• General background in dokieli documentation.
• See fork a repo to setup your own development repository and stay synchronised. Useful later to make pull requests. For example, using your fork at https://github.com/YOUR-USERNAME/dokieli :

Clone your work repository, for example:

git clone git@github.com:YOUR-USERNAME/dokieli
cd dokieli

Install packages:

yarn

Make your code updates at src/ , media/ etc.

Build eg. to create scripts/dokieli.js:

yarn build

or automatically rebuild when files change:

yarn watch

or create a minified scripts/dokieli.js:

yarn minify

To serve static files, you can use any HTTP server, e.g.:

npx serve

Tests

Unit tests

dokieli uses Vitest for unit tests.

To run unit tests, run:

yarn test:unit

Coverage reports are collected in tests/coverage.

End-to-end tests

In order to ensure intended and consistent behaviour across web browsers, dokieli uses Playwright for end-to-end browser tests.

To run end-to-end tests, run:

yarn test:e2e

Reports are collected in playwright-report/.

Some tests require authentication. To run these tests, you will need to have an .env file with credentials. See the .env.example file.

Run all tests

To run both unit and end-to-end browser tests, run:

yarn test

Code quality

We use eslint to enforce consistent code style and catch potential errors in our JavaScript code. To lint our code, run:

yarn lint

We use a husky pre-commit hook to run tests and lint before every commit. To opt-in, run:

yarn husky

You only need to run this once. After this, husky will run the linter and the tests each time you make a commit.

Creating a pull request

• Include atomic commits, small PRs: "one concern, one PR".
• In the PR comment, provide as much context and evidence to help reviewers evaluate the PR. Identify, classify, describes the changes.
• Don't forget to link PR to issue if you are solving one.
• If you run into any merge issues, checkout this git tutorial to help you resolve merge conflicts and other issues.
• You can attribute a commit to more than one author by adding one or more Co-authored-by: Name <name@example.com> per line to commit's message (after two empty lines). See github tutorial.
• To help maintain a clean Git history, consider using squash merge for PRs, especially when incorporating reviews and code additions.

Your PR is merged! okieli dokieli :tada: Thank you! :sparkles:.