Skip to content

Latest commit

 

History

History
130 lines (86 loc) · 5.05 KB

CONTRIBUTING.md

File metadata and controls

130 lines (86 loc) · 5.05 KB
Raw

Contributing to MLOS

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Environment

Getting Started

The development environment for MLOS uses conda to ease dependency management.

Devcontainer (preferred)

For a quick start, you can use the provided VSCode devcontainer configuration.

Simply open the project in VSCode and follow the prompts to build and open the devcontainer and the conda environment and additional tools will be installed automatically inside the container.

Manually

See Also: conda install instructions

Note: to support Windows we currently rely on some pre-compiled packages from conda-forge channels, which increases the conda solver time during environment create/update.

To work around this the (currently) experimental libmamba solver can be used.

See https://github.com/conda-incubator/conda-libmamba-solver#getting-started for more details.

  1. Create the mlos Conda environment.

    conda env create -f conda-envs/mlos.yml

    See the conda-envs/ directory for additional conda environment files, including those used for Windows (e.g. mlos-windows.yml).

    or

    # This will also ensure the environment is update to date using "conda env update -f conda-envs/mlos.yml"
make conda-env

    Note: the latter expects a *nix environment.

  2. Initialize the shell environment.

    conda activate mlos

Details

main is considered the primary development branch.

We expect development to follow a typical "forking" style workflow:

  1. Fork a copy of the MLOS repo in Github.

  2. Create a development (a.k.a. topic) branch off of main to work on changes.

    For instance:

    git checkout -b YourDevName/some-topic-description main

  3. Ensure all of the lint checks and tests pass.

    The easiest way to do this is to run the make commands that are also used in the CI pipeline:

    # All at once in parallel.
make all

# Or individually (for easier debugging)
make format
make check
make test
make dist-test
make doc-test

    See the documentation README for more information on documentation and its testing.

  4. Submit changes for inclusion as a Pull Request on Github.

    Some notes on organizing changes to help reviewers:

    1. Please try to keep PRs small whenver possible and don't include unnecessaary formatting changes.
    2. Larger changes can be planned in Issues, prototyped in a large draft PR for early feedback, and split into smaller PRs via discussion.
    3. All changes should include test coverage (either new or existing).

  5. PRs are associated with Github Issues and need MLOS-committers to sign-off (in addition to other CI pipeline checks like tests and lint checks to pass).

  6. Once approved, the PR can be completed using a squash merge in order to keep a nice linear history.

Distributing

You can also locally build and install from wheels like so:

  1. Build the wheel file(s)

    make dist

  2. Install it.

    # this will install just the optimizer component with SMAC support:
pip install "dist/tmp/mlos_core-latest-py3-none-any.whl[smac]"
    # this will install both the optimizer and the experiment runner:
pip install "dist/mlos_bench-latest-py3-none-any.whl[azure]"

    Note: exact versions may differ due to automatic versioning so the -latest- part is a symlink. If distributing elsewhere, adjust for the current version number in the module's dist directory.

See Also