diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md deleted file mode 100644 index 1cd9882d9..000000000 --- a/.github/CONTRIBUTING.md +++ /dev/null @@ -1,22 +0,0 @@ -# Contributing to OpenFE - -Thanks for contributing to the OpenFE software project! -Read our [code of conduct](../Code_of_Conduct.md) to understand the standards you must adhere to. - -## Questions - -If you have any questions on using the OpenFE package, reach out on the "Discussions" tab above to start a conversation! -We are happy to get you started in using our software. - -## Issues - -If you think you have encountered a software issue, please raise this on the "Issues" tab in Github. -In general the more details you can provide the better, -we recommend reading section 3.3 of [this article](https://livecomsjournal.org/index.php/livecoms/article/view/v3i1e1473) -to understand the problem solving process. - -## Contributing - -We welcome any fixes or code contributions. -Note that any contributions made must be made under a MIT license. -Feel free to reach out to the developer team who can assist you in this process. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..579996e6e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,79 @@ +# Contributing to OpenFE + +We welcome fixes and code contributions to **openfe** and the [larger OpenFE ecosystem](https://github.com/OpenFreeEnergy). +Note that any contributions made must be made under a MIT license. + +Please read our [code of conduct](Code_of_Conduct.md) to understand the standards you must adhere to. + +## Installing a Development Environment + +### Installing openfe for development + +``` bash +mamba env create -f environment.yml +mamba activate openfe_env +python -m pip install -e --no-deps . +``` + +### Multi-project development +It's common to need to develop *openfe** in tandem with another OpenFE Ecosystem package. +For example, you may want to add some feature to **gufe**, and make sure that its functionality works as intended with **openfe**. + +To build dev versions of both packages locally, follow the above instructions for installing **openfe** for development, then (using **gufe** as an example): + +``` bash +mamba activate openfe_env # if not already activated +git clone git@github.com:OpenFreeEnergy/gufe.git +cd gufe/ +pip install -e . +``` + +To make sure the CI tests run properly on your PR, in `openfe/env.yaml` and `openfe/docs/env.yaml`, pin **gufe** to your dev working branch + +```yaml +... + + - pip: + - git+https://github.com/OpenFreeEnergy/gufe@feat/your-dev-branch +``` +Once tests pass, the PR is approved, and you're ready to merge: + 1. merge in the **gufe** PR + 2. switch `openfe/env.yaml` and `openfe/docs/env.yaml` back to `gufe@main`, then re-run CI. + +## Contribution Guidelines + +### Use semantic branch names +- Start branch names with one of the following "types", followed by a short description or issue number. + - `feat/`: new user-facing feature + - `fix/`: bugfixes + - `docs/`: changes to documentation only + - `refactor/`: refactoring that does not change behavior + - `ci/`: changes to CI workflows + + + +### CI, linting, style guide +- CI tests, docs, etc, will run on every PR that has `main` or a branch that begins with `feat/` as a target. +- Add a news item for any user-facing changes. +- Rebase or merge, we don't care, but keep your branch up to date with `main`. +- Always "squash and merge" to keep the git log readable. +- Use [numpy docstrings](https://numpydoc.readthedocs.io/en/latest/format.html) +- We encourage but do not require [type hints](https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html). +- Every PR should have tests that cover changes. You will see the coverage report in CI. +- Any pins to versions in `environment.yaml` etc. need to have a comment explaining the purpose of the pin and/or a link to the related issue. + + + + + +### Review process +- In general, push PRs early so that work is visible, but leave a PR in draft-mode until you want it to be reviewed by the team. Once it's marked as "ready for review," the OpenFE team will assign a reviewer. + +### Larger contributions (multi-PR contributions) +- [Open an issue](https://github.com/OpenFreeEnergy/openfe/issues) describing the feature you want to contribute and get feedback from the OpenFE team. Use sub-issues to break down larger, more complex projects. + - You are encouraged to add sub issues throughout the development process. + - Try to aim for 1 PR per issue! +- You may want to request that maintainers create a designated branch for large features that require multiple PRs. This way, the `feat/` branch can be the target of several smaller PRs. +- Break your work into smaller issue/PR pairs that target `feat/my-new-feature`, and ask for frequent reviews. + + \ No newline at end of file diff --git a/README.md b/README.md index fdf1f5f67..d348102f2 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -[![Logo](https://img.shields.io/badge/OSMF-OpenFreeEnergy-%23002f4a)](https://openfree.energy/) +[![Logo](https://img.shields.io/badge/OMSF-OpenFreeEnergy-8A2283)](https://openfree.energy/) [![build](https://github.com/OpenFreeEnergy/openfe/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/OpenFreeEnergy/openfe/actions/workflows/ci.yaml) [![coverage](https://codecov.io/gh/OpenFreeEnergy/openfe/branch/main/graph/badge.svg)](https://codecov.io/gh/OpenFreeEnergy/openfe) [![documentation](https://readthedocs.org/projects/openfe/badge/?version=stable)](https://docs.openfree.energy/en/stable/?badge=stable) @@ -7,8 +7,7 @@ # `openfe` - A Python package for executing alchemical free energy calculations. -The `openfe` package is the flagship project of [Open Free Energy](https://openfree.energy), -a pre competitive consortium aiming to provide robust, permissively licensed open source tools for molecular simulation in the drug discovery field. +The `openfe` package is the flagship project of [Open Free Energy](https://openfree.energy), a pre competitive consortium aiming to provide robust, permissively licensed open source tools for molecular simulation in the drug discovery field. Using `openfe` you can easily plan and execute alchemical free energy calculations. @@ -24,7 +23,10 @@ This library is made available under the [MIT](https://opensource.org/licenses/M ### Latest release -The latest release of `openfe` can be installed via `mamba`, `docker`, or a `single file installer`. See [our installation instructions](https://docs.openfree.energy/en/stable/installation.html) for more details. +The latest release of `openfe` can be installed via `mamba`, `docker`, or a `single file installer`. + +See [our installation instructions](https://docs.openfree.energy/en/stable/installation.html) for more details. + Dependencies can be installed via conda through: ### Development version @@ -35,6 +37,7 @@ First install the package dependencies using `mamba`: ```bash mamba env create -f environment.yml +mamba activate openfe_env ``` The openfe library can then be installed via: @@ -43,6 +46,17 @@ The openfe library can then be installed via: python -m pip install --no-deps . ``` +## Issues + +If you think you have encountered a software issue, please raise this on the [Issues tab](https://github.com/OpenFreeEnergy/openfe/issues) in Github. +In general, the more details you can provide the better. +We recommend reading section 3.3 of [this article](https://livecomsjournal.org/index.php/livecoms/article/view/v3i1e1473) to understand the problem solving process. + + +## Discussions + +If you have general questions about using OpenFE (i.e. not bugs or feature requests), reach out on the ["Discussions" tab above](https://github.com/OpenFreeEnergy/openfe/discussions) to start a conversation! + ## Authors The OpenFE development team.