DOC: Update CONTRIBUTING.md with local services setup and test instructions#1709
Conversation
…ctions Closes openml#1708 - Add 'Starting Local Services' section with required permission step (chown/chmod data/php) before running docker compose, as implemented in openml#1697 - Extend testing guide with OPENML_USE_LOCAL_SERVICES env var instructions for running pytest against local services (Linux/macOS and Windows)
nishtha-agarwal-211
changed the title
There was a problem hiding this comment.
Pull request overview
Updates contributor documentation so developers can start the local Dockerized OpenML services and run the test suite against them (to mirror CI behavior).
Changes:
- Add a “Starting Local Services” section with initial permission setup +
openml/servicesstartup instructions. - Extend the testing guide with
OPENML_USE_LOCAL_SERVICES="true"instructions for Linux/macOS and Windows. - Fix formatting/indentation of the final MkDocs preview line.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| 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 |
There was a problem hiding this comment.
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/).
| 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 |
| ```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 |
There was a problem hiding this comment.
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.
| chmod -R 777 data/php | |
| chmod -R a+rw data/php |
| ```bash | ||
| git clone https://github.com/openml/services.git | ||
| cd services | ||
| docker compose --profile rest-api --profile minio up -d | ||
| ``` |
There was a problem hiding this comment.
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.
|
|
||
| ### 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: |
There was a problem hiding this comment.
“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).
| 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: |
Closes #1708
Metadata
Details
What does this PR implement/fix?
Adds two missing documentation sections to CONTRIBUTING.md:
Starting Local Services — Documents the required
chown/chmodpermission step ondata/phpbefore runningdocker compose, and the exact clone + startup commands for theopenml/servicesrepo (with--profile rest-api --profile minio), as introduced in [MNT] Update CI/CD with local test server and dependency matrix #1697.Running tests with local services — Extends the testing guide with instructions to set the
OPENML_USE_LOCAL_SERVICES="true"environment variable before runningpytest, for both Linux/macOS and Windows.Why is this necessary?
The CI was switched to run tests against local Docker services in #1629 and #1697, but the contributor documentation was never updated to reflect this. Contributors had no documented way to replicate the CI test run locally.