Skip to content

DOC: Update CONTRIBUTING.md with local services setup and test instructions #1709

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
nishtha-agarwal-211 wants to merge 2 commits into
base: main
Choose a base branch
from
+31 −1
Open

DOC: Update CONTRIBUTING.md with local services setup and test instructions #1709

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
91bb257
DOC: Update CONTRIBUTING.md with local services setup and test instru…
nishtha-agarwal-211 Mar 10, 2026
2d1a8d8
Merge branch 'main' into doc/update-local-services-testing-docs
nishtha-agarwal-211 Apr 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 31 additions & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,13 +76,43 @@ However, it is also possible to use the [openml-python docker image](https://git
pre-commit install
```

### Starting Local Services

The test suite runs against local services via Docker. Before starting the services for the first time, set the required file permissions:
Copy link

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

“The test suite runs against local services via Docker” reads as the default behavior, but later instructions indicate local services are opt-in via OPENML_USE_LOCAL_SERVICES. Consider rephrasing to avoid confusion (e.g., CI runs against local services, or tests can be run against local services).

Suggested change
The test suite runs against local services via Docker. Before starting the services for the first time, set the required file permissions:
The test suite can be run against local services via Docker. Before starting the services for the first time, set the required file permissions:

Copilot uses AI. Check for mistakes.

```bash
chown -R www-data:www-data data/php
# Or, if the above fails (e.g. because `www-data` does not exist on your system):
chmod -R 777 data/php
Copy link

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

chown -R www-data:www-data ... typically requires sudo, and the fallback chmod -R 777 is overly permissive. To better match the CI setup and reduce permissions risk, consider documenting the chmod -R a+rw ... approach (CI uses this on ./data and ./logs in .github/workflows/test.yml:125-127) or another least-privilege alternative.

Suggested change
chmod -R 777 data/php
chmod -R a+rw data/php

Copilot uses AI. Check for mistakes.
```

Then clone the [openml/services](https://github.com/openml/services) repository and start the services:

```bash
git clone https://github.com/openml/services.git
cd services
Comment on lines +81 to +93
Copy link

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The permission commands reference data/php before the openml/services repo is cloned/entered; following these steps in order will likely fail with “No such file or directory”. Consider reordering to clone/cd into services first (or explicitly prefix the path with services/).

Suggested change
The test suite runs against local services via Docker. Before starting the services for the first time, set the required file permissions:
```bash
chown -R www-data:www-data data/php
# Or, if the above fails (e.g. because `www-data` does not exist on your system):
chmod -R 777 data/php
```
Then clone the [openml/services](https://github.com/openml/services) repository and start the services:
```bash
git clone https://github.com/openml/services.git
cd services
The test suite runs against local services via Docker. Before starting the services for the first time, clone the [openml/services](https://github.com/openml/services) repository, enter it, and set the required file permissions:
```bash
git clone https://github.com/openml/services.git
cd services
chown -R www-data:www-data data/php
# Or, if the above fails (e.g. because `www-data` does not exist on your system):
chmod -R 777 data/php

Copilot uses AI. Check for mistakes.
docker compose --profile rest-api --profile minio up -d
```
Comment on lines +91 to +95
Copy link

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documented docker compose command doesn’t match the CI service startup (CI uses --profile rest-api --profile minio --profile evaluation-engine plus data/logs permission tweaks in .github/workflows/test.yml:125-127). If the goal is to let contributors replicate CI locally, update the command or clarify why evaluation-engine (and the extra chmods) are not needed here.

Copilot uses AI. Check for mistakes.

### Testing (Your Installation)
To test your installation and run the tests for the first time, run the following from the repository folder:
```bash
pytest tests
```
For Windows systems, you may need to add `pytest` to PATH before executing the command.

To run tests against the local services (started with `docker compose` above), set the `OPENML_USE_LOCAL_SERVICES` environment variable before running `pytest`:

```bash
# Linux/macOS
export OPENML_USE_LOCAL_SERVICES="true"
pytest tests

# Windows
$env:OPENML_USE_LOCAL_SERVICES = "true"
pytest tests
```

Executing a specific unit test can be done by specifying the module, test case, and test.
You may then run a specific module, test case, or unit test respectively:
```bash
Expand Down Expand Up @@ -214,4 +244,4 @@ When dependencies are installed, run
```bash
mkdocs serve
```
This will open a preview of the website.
This will open a preview of the website.
Loading