# Contributing to MLflow We welcome community contributions to MLflow. This page provides useful information about contributing to MLflow. **Table of Contents** - [Governance](#governance) - [Core Members](#core-members) - [Contribution process](#contribution-process) - [Contribution guidelines](#contribution-guidelines) - [Write designs for significant changes](#write-designs-for-significant-changes) - [Make changes backwards compatible](#make-changes-backwards-compatible) - [Consider introducing new features as MLflow Plugins](#consider-introducing-new-features-as-mlflow-plugins) - [Python Style Guide](#python-style-guide) - [Setting up the repository](#setting-up-the-repository) - [Developing and testing MLflow](#developing-and-testing-mlflow) - [Environment Setup and Python configuration](#environment-setup-and-python-configuration) - [Automated Python development environment configuration](#automated-python-development-environment-configuration) - [Manual Python development environment configuration](#manual-python-development-environment-configuration) - [JavaScript and UI](#javascript-and-ui) - [Install Node Module Dependencies](#install-node-module-dependencies) - [Install Node Modules](#install-node-modules) - [Launching the Development UI](#launching-the-development-ui) - [Running the Javascript Dev Server](#running-the-javascript-dev-server) - [Testing a React Component](#testing-a-react-component) - [Linting Javascript Code](#linting-javascript-code) - [R](#r) - [Java](#java) - [Python](#python) - [Writing Python Tests](#writing-python-tests) - [Running Python Tests](#running-python-tests) - [Python Client](#python-client) - [Python Model Flavors](python-model-flavors) - [Python Server](#python-server) - [Building Protobuf Files](#building-protobuf-files) - [Database Schema Changes](#database-schema-changes) - [Writing MLflow Examples](#writing-mlflow-examples) - [Building a Distributable Artifact](#building-a-distributable-artifact) - [Writing Docs](#writing-docs) - [Sign your work](#sign-your-work) - [Code of Conduct](#code-of-conduct) ## Governance Governance of MLflow is conducted by the Technical Steering Committee (TSC), which currently includes the following members: - Patrick Wendell () - Reynold Xin () - Matei Zaharia () The founding technical charter can be found [here](https://github.com/mlflow/mlflow/blob/master/mlflow-charter.pdf). ## Core Members MLflow is currently maintained by the following core members with significant contributions from hundreds of exceptionally talented community members. - [Harutaka Kawamura](https://github.com/harupy) - [Weichen Xu](https://github.com/WeichenXu123) - [Corey Zumar](https://github.com/dbczumar) - [Ben Wilson](https://github.com/BenWilson2) - [Serena Ruan](https://github.com/serena-ruan) - [Yuki Watanabe](https://github.com/B-Step62) - [Daniel Lok](https://github.com/daniellok-db) - [Tomu Hirata](https://github.com/TomeHirata) - [Matt Prahl](https://github.com/mprahl) - [Gabriel Fu](https://github.com/gabrielfu) ## Contribution process The MLflow contribution process starts with filing a GitHub issue. MLflow defines four categories of issues: feature requests, bug reports, documentation fixes, and installation issues. Details about each issue type and the issue lifecycle are discussed in the [MLflow Issue Policy](https://github.com/mlflow/mlflow/blob/master/ISSUE_POLICY.md). MLflow committers actively [triage](ISSUE_TRIAGE.rst) and respond to GitHub issues. In general, we recommend waiting for feedback from an MLflow committer or community member before proceeding to implement a feature or patch. This is particularly important for [significant changes](https://github.com/mlflow/mlflow/blob/master/CONTRIBUTING.md#write-designs-for-significant-changes), and will typically be labeled during triage with `needs design`. After you have agreed upon an implementation strategy for your feature or patch with an MLflow committer, the next step is to introduce your changes (see [developing changes](https://github.com/mlflow/mlflow/blob/master/CONTRIBUTING.md#developing-and-testing-mlflow)) as a pull request against the MLflow Repository (we recommend pull requests be filed from a non-master branch on a repository fork) or as a standalone MLflow Plugin. MLflow committers actively review pull requests and are also happy to provide implementation guidance for Plugins. Once your pull request against the MLflow Repository has been merged, your corresponding changes will be automatically included in the next MLflow release. Every change is listed in the MLflow release notes and [Changelog](https://github.com/mlflow/mlflow/blob/master/CHANGELOG.md). Congratulations, you have just contributed to MLflow. We appreciate your contribution\! ## Contribution guidelines In this section, we provide guidelines to consider as you develop new features and patches for MLflow. ### Write designs for significant changes For significant changes to MLflow, we recommend outlining a design for the feature or patch and discussing it with an MLflow committer before investing heavily in implementation. During issue triage, we try to proactively identify issues require design by labeling them with `needs design`. This is particularly important if your proposed implementation: - Introduces changes or additions to the [MLflow REST API](https://mlflow.org/docs/latest/rest-api.html) - The MLflow REST API is implemented by a variety of open source and proprietary platforms. Changes to the REST API impact all of these platforms. Accordingly, we encourage developers to thoroughly explore alternatives before attempting to introduce REST API changes. - Introduces new user-facing MLflow APIs - MLflow's API surface is carefully designed to generalize across a variety of common ML operations. It is important to ensure that new APIs are broadly useful to ML developers, easy to work with, and simple yet powerful. - Adds new library dependencies to MLflow - Makes changes to critical internal abstractions. Examples include: the Tracking Artifact Repository, the Tracking Abstract Store, and the Model Registry Abstract Store. ### Make changes backwards compatible MLflow's users rely on specific platform and API behaviors in their daily workflows. As new versions of MLflow are developed and released, it is important to ensure that users' workflows continue to operate as expected. Accordingly, please take care to consider backwards compatibility when introducing changes to the MLflow code base. If you are unsure of the backwards compatibility implications of a particular change, feel free to ask an MLflow committer or community member for input. In addition to public APIs, any Python APIs within MLflow that are designated with the annotation `@developer_stable` must remain backwards compatible. Any contribution that adds features, modifies behavior, or otherwise changes the functionality within the scope of these classes or methods will be closely reviewed by maintainers, and additional backwards compatibility testing may be requested. ### Consider introducing new features as MLflow Plugins [MLflow Plugins](https://mlflow.org/docs/latest/plugins.html) enable integration of third-party modules with many of MLflow's components, allowing you to maintain and iterate on certain features independently of the MLflow Repository. Before implementing changes to the MLflow code base, consider whether your feature might be better structured as an MLflow Plugin. MLflow Plugins are a great choice for the following types of changes: 1. Supporting a new storage platform for MLflow artifacts 2. Introducing a new implementation of the MLflow Tracking backend ([Abstract Store](https://github.com/mlflow/mlflow/blob/cdc6a651d5af0f29bd448d2c87a198cf5d32792b/mlflow/store/tracking/abstract_store.py)) for a particular platform 3. Introducing a new implementation of the Model Registry backend ([Abstract Store](https://github.com/mlflow/mlflow/blob/cdc6a651d5af0f29bd448d2c87a198cf5d32792b/mlflow/store/model_registry/abstract_store.py)) for a particular platform 4. Automatically capturing and recording information about MLflow Runs created in specific environments MLflow committers and community members are happy to provide assistance with the development and review of new MLflow Plugins. Finally, MLflow maintains a list of Plugins developed by community members, which is located at . This is an excellent way to inform MLflow users about your exciting new Plugins. To list your plugin, simply introduce a new pull request against the [corresponding docs section of the MLflow code base](https://github.com/mlflow/mlflow/blob/cdc6a651d5af0f29bd448d2c87a198cf5d32792b/docs/source/plugins.rst#community-plugins). For more information about Plugins, see . ### Python Style Guide ##### Docstrings We follow [Google's Python Style Guide](https://google.github.io/styleguide/pyguide.html) for writing docstrings. Make sure your docstrings adhere to this style guide. ###### Code Style We use [prettier](https://prettier.io/), [blacken-docs](https://pypi.org/project/blacken-docs/), [ruff](https://github.com/astral-sh/ruff), and a number of custom lint checking scripts in our CI via pre-commit Git hooks. If your code passes the CI checks, it's formatted correctly. To validate that your local versions of the above libraries match those in the mlflow CI, refer to [lint-requirements.txt](https://github.com/mlflow/mlflow/blob/master/requirements/lint-requirements.txt). You can compare these versions with your local using pip: ```bash pip show ruff ``` ## Setting up the repository To set up the MLflow repository, run the following commands: ```bash # Clone the repository git clone --recurse-submodules git@github.com:/mlflow.git # The alternative way of cloning through https may cause permission error during branch push # git clone --recurse-submodules https://github.com//mlflow.git # Add the upstream repository cd mlflow git remote add upstream git@github.com:mlflow/mlflow.git ``` If you cloned the repository before without `--recurse-submodules`, run this command to fetch submodules: ```bash git submodule update --init --recursive ``` ## Developing and testing MLflow The majority of the MLflow codebase is developed in Python. This includes the CLI, Tracking Server, Artifact Repositories (e.g., S3 or Azure Blob Storage backends), and of course the Python fluent, tracking, and model APIs. ### Environment Setup and Python configuration Having a standardized development environment is advisable when working on MLflow. Creating an environment that contains the required Python packages (and versions), linting tools, and environment configurations will help to prevent unnecessary CI failures when filing a PR. A correctly configured local environment will also allow you to run tests locally in an environment that mimics that of the CI execution environment. There are three means of setting up a base Python development environment for MLflow: GitHub Codespaces, automated (through the [dev-env-setup.sh](https://github.com/mlflow/mlflow/tree/master/dev/dev-env-setup.sh) script) or manual. Even in a manual-based approach (i.e., testing functionality of a specific version of a model flavor's package version), the automated script can save a great deal of time and reduce errors in creating the environment. #### GitHub Codespaces 1. Navigate to https://github.com/mlflow/mlflow.git. 2. Above the file list, click `Code`, then select `Create codespace` and wait for your codespace to be created. See [Quickstart for GitHub Codespaces](https://docs.github.com/en/codespaces/getting-started/quickstart) for more information. #### Automated Python development environment configuration The automated development environment setup script ([dev-env-setup.sh](https://github.com/mlflow/mlflow/tree/master/dev/dev-env-setup.sh)) can be used to setup a development environment that is configured with all of the dependencies required and the environment configuration needed to develop and locally test the Python code portions of MLflow. This CLI tool's readme can be accessed via the root of the mlflow repository as follows: ```bash dev/dev-env-setup.sh -h ``` An example usage of this script that will build a development environment using `virtualenv` and the minimum supported Python version (to ensure compatibility) is: ```bash dev/dev-env-setup.sh -d .venvs/mlflow-dev -q ``` The `-q` parameter is to "quiet" the pip install processes preventing stdout printing during installation. It is advised to follow all of the prompts to ensure that the configuration of the environment, as well as git, are completed so that your PR process is as effortless as possible. **Note** Frequently, a specific version of a library is required in order to validate a feature's compatibility with older versions. Modifying your primary development environment to test one-off compatibility can be very error-prone and result in an environment that is significantly different from that of the CI test environment. To support this use case, the automated script can be used to create an environment that can be easily modified to support testing a particular version of a model flavor in an isolated environment. Simply run the `dev-env-setup.sh` script, activate the new environment, and install the required version for testing. Example of installing an older version of `scikit-learn` to perform isolated testing: ```bash dev/dev-env-setup.sh -d ~/.venvs/sklearn-test -q source ~/.venvs/sklearn-test/bin/activate pip freeze | grep "scikit-learn" >> scikit-learn==1.0.2 pip install scikit-learn==1.0.1 pip freeze | grep "scikit-learn" >> scikit-learn==1.0.1 ``` #### Manual Python development environment configuration The manual process is recommended if you are going to use Conda or if you are fond of terminal setup processes. To start with the manual process, ensure that you have either conda or virtualenv installed. First, ensure that your name and email are [configured in git](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup) so that you can [sign your work](#sign-your-work) when committing code changes and opening pull requests: ```bash git config --global user.name "Your Name" git config --global user.email yourname@example.com ``` For convenience, we provide a pre-commit git hook that validates that commits are signed-off and runs `ruff check --fix` and `ruff format` to ensure the code will pass the lint check for python. You can enable it by running: ```bash pre-commit install --install-hooks ``` Then, install the Python MLflow package from source - this is required for developing & testing changes across all languages and APIs. We recommend installing MLflow in its own conda environment by running the following from your checkout of MLflow: ```bash conda create --name mlflow-dev-env python=3.8 conda activate mlflow-dev-env pip install -e '.[extras]' # installs mlflow from current checkout with some useful extra utilities ``` If you plan on doing development and testing, you will also need to install the following into the conda environment: ```bash pip install -r requirements/test-requirements.txt pip install -e '.[extras]' # installs mlflow from current checkout pip install -e tests/resources/mlflow-test-plugin # installs `mlflow-test-plugin` that is required for running certain MLflow tests ``` You may need to run `conda install cmake` for the test requirements to properly install, as `onnx` needs `cmake`. Ensure [Docker](https://www.docker.com/) is installed. Finally, we use `pytest` to test all Python contributed code. Install `pytest`: ```bash pip install pytest ``` ### JavaScript and UI The MLflow UI is written in JavaScript. `yarn` is required to run the Javascript dev server and the tracking UI. You can verify that `yarn` is on the PATH by running `yarn -v`, and [install yarn](https://classic.yarnpkg.com/lang/en/docs/install) if needed. #### Install Node Module Dependencies On OSX, install the following packages required by the node modules: ```bash brew install pixman cairo pango jpeg ``` Linux/Windows users will need to source these dependencies using the appropriate package manager on their platforms. #### Install Node Modules Before running the Javascript dev server or building a distributable wheel, install Javascript dependencies via: ```bash cd mlflow/server/js yarn install cd - # return to root repository directory ``` If modifying dependencies in `mlflow/server/js/package.json`, run `yarn upgrade` within `mlflow/server/js` to install the updated dependencies. #### Launching the Development UI We recommend [Running the Javascript Dev Server](#running-the-javascript-dev-server) - otherwise, the tracking frontend will request files in the `mlflow/server/js/build` directory, which is not checked into Git. Alternatively, you can generate the necessary files in `mlflow/server/js/build` as described in [Building a Distributable Artifact](#building-a-distributable-artifact). #### Running the Javascript Dev Server [Install Node Modules](#install-node-modules), then run the following in two separate shells: In one shell: ```bash mlflow server ``` And in another shell: ```bash cd mlflow/server/js yarn start ``` The Javascript Dev Server will run at and the MLflow server will run at and show runs logged in `./mlruns`. **Note:** On some versions of MacOS, the "Airplay Receiver" process runs on port 5000 by default, which can cause [network request failures](https://stackoverflow.com/questions/72369320/why-always-something-is-running-at-port-5000-on-my-mac). If you are encountering such issues, disable the process via system settings, or specify another port (e.g. `mlflow server --port 8000`). If specifying a different port, please set the following environment variables before running `yarn start`: - `MLFLOW_PROXY=` - `MLFLOW_DEV_PROXY_MODE=false` For example: ``` $ mlflow server --port 8000 ... (in a separate shell) $ export MLFLOW_PROXY=http://127.0.0.1:8000 $ export MLFLOW_DEV_PROXY_MODE=false $ yarn install $ yarn start ... (UI should now be visible at localhost:3000) ``` #### Testing a React Component Add a test file in the same directory as the newly created React component. For example, `CompareRunBox.test.js` should be added in the same directory as `CompareRunBox.js`. Next, in `mlflow/server/js`, run the following command to start the test. ```bash # Run tests in CompareRunBox.test.js yarn test CompareRunBox.test.js # Run tests with a name that matches 'plot' in CompareRunBox.test.js yarn test CompareRunBox.test.js -t 'plot' # Run all tests yarn test ``` #### Linting Javascript Code In `mlflow/server/js`, run the following command to lint your code. ```bash # Note this command only fixes auto-fixable issues (e.g. remove trailing whitespace) yarn lint:fix ``` ### R If contributing to MLflow's R APIs, install [R](https://cloud.r-project.org/) and make sure that you have satisfied all the [Environment Setup and Python configuration](#environment-setup-and-python-configuration). The `mlflow/R/mlflow` directory contains R wrappers for the Projects, Tracking and Models components. These wrappers depend on the Python package, so first install the Python package in a conda environment: ```bash # Note that we don't pass the -e flag to pip, as the R tests attempt to run the MLflow UI # via the CLI, which will not work if we run against the development tracking server pip install . ``` [Install R](https://cloud.r-project.org/), then run the following to install dependencies for building MLflow locally: ```bash cd mlflow/R/mlflow NOT_CRAN=true Rscript -e 'install.packages("devtools", repos = "https://cloud.r-project.org")' NOT_CRAN=true Rscript -e 'devtools::install_deps(dependencies = TRUE)' ``` Build the R client via: ```bash R CMD build . ``` Run tests: ```bash R CMD check --no-build-vignettes --no-manual --no-tests mlflow*tar.gz cd tests NOT_CRAN=true LINTR_COMMENT_BOT=false Rscript ../.run-tests.R cd - ``` Run linter: ```bash Rscript -e 'lintr::lint_package()' ``` If opening a PR that makes API changes, please regenerate API documentation as described in [Writing Docs](#writing-docs) and commit the updated docs to your PR branch. When developing, you can make Python changes available in R by running (from mlflow/R/mlflow): ```bash Rscript -e 'reticulate::conda_install("r-mlflow", "../../../.", pip = TRUE)' ``` Please also follow the recommendations from the [Advanced R - Style Guide](http://adv-r.had.co.nz/Style.html) regarding naming and styling. ### Java If contributing to MLflow's Java APIs or modifying Java documentation, install [Java](https://www.java.com/) and [Apache Maven](https://maven.apache.org/download.cgi). A certain MLflow module is implemented in Java, under the `mlflow/java/` directory. This is the Java Tracking API client (`mlflow/java/client`). Other Java functionality (like artifact storage) depends on the Python package, so first install the Python package in a conda environment as described in [Environment Setup and Python configuration](#environment-setup-and-python-configuration). [Install](https://www.oracle.com/technetwork/java/javase/downloads/index.html) the Java 8 JDK (or above), and [download](https://maven.apache.org/download.cgi) and [install](https://maven.apache.org/install.html) Maven. You can then build and run tests via: ```bash cd mlflow/java mvn compile test ``` If opening a PR that makes API changes, please regenerate API documentation as described in [Writing Docs](#writing-docs) and commit the updated docs to your PR branch. ### Python If you are contributing in Python, make sure that you have satisfied all the [Environment Setup and Python configuration](#environment-setup-and-python-configuration), including installing `pytest`, as you will need it for the sections described below. #### Writing Python Tests If your PR includes code that isn't currently covered by our tests (e.g. adding a new flavor, adding autolog support to a flavor, etc.), you should write tests that cover your new code. Your tests should be added to the relevant file under `tests`, or if there is no appropriate file, in a new file prefixed with `test_` so that `pytest` includes that file for testing. If your tests require usage of a tracking URI, the [pytest fixture](https://docs.pytest.org/en/stable/explanation/fixtures.html) [`tracking_uri_mock`](https://github.com/mlflow/mlflow/blob/42c02c800a827fc1c78308ff017c31145143b52e/tests/conftest.py#L542) is automatically set up for every tests. It sets up a mock tracking URI that will set itself up before your test runs and tear itself down after. By default, runs are logged under a local temporary directory that's unique to each test and torn down immediately after test execution. To disable this behavior, decorate your test function with `@pytest.mark.notrackingurimock` #### Running Python Tests Verify that the unit tests & linter pass before submitting a pull request by running: We use [ruff](https://docs.astral.sh/ruff/) to ensure a consistent code format. You can auto-format your code by running: ```bash ruff format . ruff check . ``` Then, verify that the unit tests & linter pass before submitting a pull request by running: ```bash pre-commit run --all-files pytest tests --quiet --requires-ssh --ignore-flavors --serve-wheel \ --ignore=tests/examples --ignore=tests/evaluate ``` We use [pytest](https://docs.pytest.org/en/latest/contents.html) to run Python tests. You can run tests for one or more test directories or files via `pytest [file_or_dir] ... [file_or_dir]`. For example, to run all pytest tests, you can run: ```bash pytest tests/pyfunc ``` Note: Certain model tests are not well-isolated (can result in OOMs when run in the same Python process), so simply invoking `pytest` or `pytest tests` may not work. If you'd like to run multiple model tests, we recommend doing so via separate `pytest` invocations, e.g. `pytest tests/sklearn && pytest tests/tensorflow` If opening a PR that changes or adds new APIs, please update or add Python documentation as described in [Writing Docs](#writing-docs) and commit the docs to your PR branch. #### Python Client For the client, if you are adding new model flavors, follow the instructions below. ##### Python Model Flavors If you are adding new framework flavor support, you'll need to modify `pytest` and Github action configurations so tests for your code can run properly. Generally, the files you'll have to edit are: 1. `.github/workflows/master.yml`: lines where pytest runs with `--ignore-flavors` flag 1. Add your tests to the ignore list, where the other frameworks are ignored 2. Add a pytest command for your tests along with the other framework tests (as a separate command to avoid OOM issues) 2. `requirements/test-requirements.txt`: add your framework and version to the list of requirements You can see an example of a [flavor PR](https://github.com/mlflow/mlflow/pull/2136/files). #### Python Server For the Python server, you can contribute in these two areas described below. ##### Building Protobuf Files To build protobuf files, simply run `./dev/generate-protos.sh`. The required `protoc` version is `3.19.4`. You can find the URL of a system-appropriate installation of `protoc` at , e.g. if you're on 64-bit Mac OSX. Alternatively, you can comment `/autoformat` on your PR to automatically compile the protobuf files and update the autogenerated code. Once the autogenerated code is updated, verify that `.proto` files and autogenerated code are in sync by running `./dev/test-generate-protos.sh`. ##### Database Schema Changes MLflow's Tracking component supports storing experiment and run data in a SQL backend. To make changes to the tracking database schema, run the following from your checkout of MLflow: ```bash # starting at the root of the project $ pwd ~/mlflow $ cd mlflow # MLflow relies on Alembic (https://alembic.sqlalchemy.org) for schema migrations. $ alembic -c mlflow/store/db_migrations/alembic.ini revision -m "add new field to db" Generating ~/mlflow/mlflow/store/db_migrations/versions/b446d3984cfa_add_new_field_to_db.py # Update schema files $ ./tests/db/update_schemas.sh ``` These commands generate a new migration script (e.g., at `~/mlflow/mlflow/alembic/versions/12341123_add_new_field_to_db.py`) that you should then edit to add migration logic. ### Writing MLflow Examples The `mlflow/examples` directory has a collection of quickstart tutorials and various simple examples that depict MLflow tracking, project, model flavors, model registry, and serving use cases. These examples provide developers sample code, as a quick way to learn MLflow Python APIs. To facilitate review, strive for brief examples that reflect real user workflows, document how to run your example, and follow the recommended steps below. If you are contributing a new model flavor, follow these steps: 1. Follow instructions in [Python Model Flavors](#python-model-flavors) 2. Create a corresponding directory in `mlflow/examples/new-model-flavor` 3. Implement your Python training `new-model-flavor` code in this directory 4. Convert this directory's content into an [MLflow Project](https://mlflow.org/docs/latest/projects.html) executable 5. Add `README.md`, `MLproject`, and `conda.yaml` files and your code 6. Read instructions in the `mlflow/test/examples/README.md` and add a `pytest` entry in the `test/examples/test_examples.py` 7. Add a short description in the `mlflow/examples/README.md` file If you are contributing to the quickstart directory, we welcome changes to the `quickstart/mlflow_tracking.py` that make it clearer or simpler. If you'd like to provide an example of functionality that doesn't fit into the above categories, follow these steps: 1. Create a directory with meaningful name in `mlflow/examples/new-program-name` and implement your Python code 2. Create `mlflow/examples/new-program-name/README.md` with instructions how to use it 3. Read instructions in the `mlflow/test/examples/README.md`, and add a `pytest` entry in the `test/examples/test_examples.py` 4. Add a short description in the `mlflow/examples/README.md` file Finally, before filing a pull request, verify all Python tests pass. ### Building a Distributable Artifact If you would like to build a fully functional version of MLflow from your local branch for testing or a local patch fix, first [install the Node Modules](#install-node-modules), then run the following: Generate JS files in `mlflow/server/js/build`: ```bash cd mlflow/server/js yarn build ``` Build a pip-installable wheel and a compressed code archive in `dist/`: ```bash cd - python -m build ``` ### TOML formatting We use [taplo](https://taplo.tamasfe.dev/) to enforce consistent TOML formatting. You can install it by following the instructions [here](https://taplo.tamasfe.dev/cli/introduction.html). ### Excluding Symlinks from IDE Searches The `mlflow/skinny` symlink points to `../mlflow` and may cause duplicate entries in search results. To exclude it from searches, follow these steps: **VSCode:** 1. Open `Settings`. 2. Search for `search.followSymlinks` and set it to `false`. **PyCharm:** 1. Right-click `skinny/mlflow`. 2. Select `Mark Directory as` -> `Excluded`. ### Writing Docs There are two separate build systems for the MLflow documentation: #### API Docs The [API reference](https://mlflow.org/docs/latest/api_reference/) is managed by [Sphinx](https://www.sphinx-doc.org/en/master/). The content is primarily populated by our Python docstrings, which are written in reStructuredText (RST). For instructions on how to build the API docs, please check the [README.md](https://github.com/mlflow/mlflow/blob/master/docs/api_reference/README.md) in the `docs/api_reference/` subfolder. #### Main Docs The main MLflow docs (e.g. feature docs, tutorials, etc) are written using [Docusaurus](https://docusaurus.io/). The only prerequisite for building these docs is NodeJS >= 18.0. Please check out the [official NodeJS docs](https://nodejs.org/en/download) for platform-specific installation instructions. Please check the [README.md](https://github.com/mlflow/mlflow/blob/master/docs/README.md) in the `docs/` folder to get started. We're looking forward to your contributions! ### Sign your work In order to commit your work, you need to sign that you wrote the patch or otherwise have the right to pass it on as an open-source patch. If you can certify the below (from developercertificate.org): Developer Certificate of Origin Version 1.1 Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 1 Letterman Drive Suite D4700 San Francisco, CA, 94129 Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Developer's Certificate of Origin 1.1 By making a contribution to this project, I certify that: (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it. (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. Then add a line to every git commit message: Signed-off-by: Jane Smith Use your real name (sorry, no pseudonyms or anonymous contributions). You can sign your commit automatically with `git commit -s` after you set your `user.name` and `user.email` git configs. > NOTE: Failing to sign your commits will result in an inability to merge your PR! ## Code of Conduct Refer to the [MLflow Contributor Covenant Code of Conduct](./CODE_OF_CONDUCT.rst) for more information.