Contributing

Contributions to Data Workspace are welcome, such as reporting issues, requesting features, making documentation changes, or submitting code changes.

Prerequisites

• In all cases a GitHub account is needed to contribute.
• To contribute code or documentation, you must have a copy of the Data Workspace source code locally, and have certain tools installed. See Running locally for details of these.
• To contribute code, knowledge of Python is required.

Issues

Suspected issues with Data Workspace can be submitted at Data Workspace issues.
An issue that contains a minimal, reproducible example stands the best chance of being resolved. However, it is understood that this is not possible in all circumstances.

Feature requests

A feature request can be submitted using the Ideas category in Data Workspace discussions.

Documentation

The source of the documentation is in the docs/ directory of the source code, and is written using Material for mkdocs.

Changes are then submitted via a Pull Request (PR). To do this:

1. Decide on a short hyphen-separated descriptive name for your change, prefixed with docs/, for example docs/add-example.

2. Make a branch using this descriptive name:

   git checkout -b docs/add-example
   cd data-workspace
   

3. Make your changes in a text editor.

4. Preview your changes locally:

   pip install -r requirements-docs.txt  # Only needed once
   mkdocs serve
   

5. Commit your change and push to your fork. Ideally the commit message will follow the Conventional Commit specification:

   git add docs/getting-started.md  # Repeat for each file changed
   git commit -m "docs: add an example"
   git push origin docs/add-example
   

6. Raise a PR at https://github.com/uktrade/data-workspace/pulls against the master branch in data-workspace.

7. Wait for the PR to be approved and merged, and respond to any questions or suggested changes.

When the PR is merged, the documentation is deployed automatically to https://data-workspace.docs.trade.gov.uk/.

Code

Changes are submitted via a Pull Request (PR). To do this:

1. Decide on a short hyphen-separated descriptive name for your change, prefixed with the type of change. For example fix/the-bug-description.

2. Make a branch using this descriptive name:

   git checkout -b fix/a-bug-description
   

3. Make sure you can run existing tests locally, for example by running:

   make docker-test
   

   See Running tests for more details on running tests.

4. Make your changes in a text editor. In the cases of changing behaviour, this would usually include changing or adding tests within dataworkspace/dataworkspace/tests, and running them.

5. Commit your changes and push to your fork. Ideally the commit message will follow the Conventional Commit specification:

   git add my_file.py  # Repeat for each file changed
   git commit -m "fix: the bug description"
   git push origin fix/the-bug-description
   

6. Raise a PR at https://github.com/uktrade/data-workspace/pulls against the master branch of data-workspace.

7. Wait for the PR to be approved and merged, and respond to any questions or suggested changes.