Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
131 lines (94 loc) · 3.66 KB

CONTRIBUTING.md

File metadata and controls

131 lines (94 loc) · 3.66 KB
Raw

Contributing

Quick start

pnpm install
pnpm start

To use all the features from ewoksweb, an instance of ewoksserver must be running locally on the port 5000.

Such an instance can be installed and run by running

pip install ewoksserver
ewoks-server

Another ewoksserver instance (remote for example) can be used instead by setting its URL through the env variable VITE_SERVER_URL in .env.local (default: http://127.0.0.1:8000).

Similarly, the env variable VITE_SERVER_API_SUFFIX can be changed to request a different version of the ewoksserver API. Ex:

  • /api (default): requests the latest version
  • /api/v1: requests the latest v1.x version
  • /api/v1.0.0: requests a specific version (1.0.0 in this case)

Cypress tests

To run Cypress tests, the ewoksweb instance must be running (pnpm start) and the ewoksserver instance must be configured appropriately to serve the test resources:

ewoks-server --frontend-tests

Cypress tests can then be run with

pnpm cypress # in interactive GUI mode
# OR
pnpm cypress:run # to run all specs in CLI

Build

Building the ewoksweb python package

pnpm build:package
pip install build
python -m build -s

Release

Since ewoksweb is a companion package of ewoksserver, it is released as a Python package on PyPI.

To do a new release:

  1. Checkout main and verify that your working tree is clean.
  2. Edit the version in pyproject.toml
  3. Commit the change and push it to main. The CI will trigger and run the tests.

If the CI fails, the package cannot be released. Try to relaunch it to see if it was a one-off failure (can happen with Cypress). If not, fix the CI first!

After the CI succeeds, go to the Release workflow page

  1. Click on "Run workflow". Leave the checkbox asking if the release should be done on TestPyPI unchecked and click on "Run workflow" button below.
  2. Wait for the workflow to complete. Once it is done, a git tag will automatically be created with the version number.
  3. Create a Github release out of the newly added tag
  4. Write the release notes using the tags Compare page to gather the relevant changes since last release. Try to match the style of previous release notes.
  5. Click on Publish release

Congratulations, the release is done 😎!

Documentation

The documentation is composed of RST files located in doc. You can look at the Sphinx doc for information on how to write RST files.

If a new file is created, don't forget to reference it in one of the toctree directive.

Build documentation

The documentation is built with Sphinx that generates HTML pages out of the RST files. The configuration of Sphinx is in doc/conf.py.

Requirements (including Sphinx) can be installed with

pip install [--user] .[doc]

Then, build the documentation with

sphinx-build doc build/sphinx/html -E -a

The generated HTML pages will be available in build/sphinx/html. You can browse them by opening build/sphinx/html/index.html in your browser.

When developing/writing doc, sphinx-autobuild can be used to automatically rebuild the documentation on changes

sphinx-autobuild doc build/sphinx/html

The dynamic build will then be served on http://127.0.0.1:8000/.