From 110ff103ec3cf51d2fb5840b5e4716caa69d9e88 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 14 Oct 2025 13:19:44 -0700 Subject: [PATCH 1/5] first pass at moving things into CONTRIBUTING and README --- CONTRIBUTING.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 16 ++++++++++++++-- 2 files changed, 62 insertions(+), 2 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..75c1976e9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,48 @@ +# Contributing to OpenFE + +We welcome any fixes or code contributions to the **openfe** and the larger OpenFE ecosystem. +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 Dev Environment + +It's common to need to develop openfe and gufe in tandem, to do so: +- gufe is strictly upstream of openfe, meaning that all gufe code should be test in gufe. + +- mamba create -f env.yaml in openfe +- pip install -e . # in openfe/dev_branch +- pip install -e . # in gufe/dev_branch + +to make CI test the environments properly; +- in openfe/env.yaml and openfe/docs/env.yaml, pin gufe to your dev working branch + +once you're ready to merge: +- merge in gufe PR +- switch openfe env.yamls back to gufe@main, then push + + +## Contributing a new feature (multi-PR contributing) +- open an issue describing the feature you want to contribute + - use sub issues for larger, more complex project. 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, you can work off of a fork, with this feat/ branch as the target. +- make a feat/my-new-feature branch that will be long-lived branch +- break your work into smaller issue/PR pairs that target `feat/my-new-feature`, and ask for frequent reviews. +- PR title should be essentially a changelog entry + +## CI, linting, style guide +- CI tests, docs, etc, will run on every PR that as `main` as a target. +- pre-commit comment +- rebase or merge, we don't care, but keep your branch up to date with `main` +- SQUASH ALWAYS 🍠 +- [numpy docstrings](https://numpydoc.readthedocs.io/en/latest/format.html), use type hinting as much as is reasonable. +- tests in every PR +- using `precommit` locally: + - pyproject.toml +- any pins to versions in environments etc. need to have a comment explaining why, linking to the related issue, etc. + +## Review process +- In general, push PRs early so that work is visibile, 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. + +# TODO: ai use disclosure \ No newline at end of file diff --git a/README.md b/README.md index fdf1f5f67..80a893dca 100644 --- a/README.md +++ b/README.md @@ -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. @@ -43,6 +42,19 @@ 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 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 any questions on using the OpenFE package, reach out on the ["Discussions" tab above](https://github.com/OpenFreeEnergy/openfe/discussions) to start a conversation! +We are happy to get you started in using our software. + ## Authors The OpenFE development team. From 77ba671d1546efed2e4b93c1e1a04ec3926317e1 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 14 Oct 2025 14:04:08 -0700 Subject: [PATCH 2/5] updates to README --- README.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 80a893dca..9956ec8c2 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) @@ -44,16 +44,14 @@ python -m pip install --no-deps . ## 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. +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 any questions on using the OpenFE package, reach out on the ["Discussions" tab above](https://github.com/OpenFreeEnergy/openfe/discussions) to start a conversation! -We are happy to get you started in using our software. +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 From 41caaf7d107cd5346e45f7450fe27e05ee79a43a Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 14 Oct 2025 14:23:22 -0700 Subject: [PATCH 3/5] formatting README --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 9956ec8c2..d348102f2 100644 --- a/README.md +++ b/README.md @@ -23,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 @@ -34,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: From 738570c94381ea6f94df8f667248fe824cb30b59 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 14 Oct 2025 14:47:03 -0700 Subject: [PATCH 4/5] first draft of contributing guidelines --- CONTRIBUTING.md | 97 ++++++++++++++++++++++++++++++++----------------- 1 file changed, 64 insertions(+), 33 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 75c1976e9..579996e6e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,48 +1,79 @@ # Contributing to OpenFE -We welcome any fixes or code contributions to the **openfe** and the larger OpenFE ecosystem. +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 Dev Environment +## Installing a Development Environment -It's common to need to develop openfe and gufe in tandem, to do so: -- gufe is strictly upstream of openfe, meaning that all gufe code should be test in gufe. +### Installing openfe for development -- mamba create -f env.yaml in openfe -- pip install -e . # in openfe/dev_branch -- pip install -e . # in gufe/dev_branch +``` bash +mamba env create -f environment.yml +mamba activate openfe_env +python -m pip install -e --no-deps . +``` -to make CI test the environments properly; -- in openfe/env.yaml and openfe/docs/env.yaml, pin gufe to your dev working branch +### 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**. -once you're ready to merge: -- merge in gufe PR -- switch openfe env.yamls back to gufe@main, then push +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 . +``` -## Contributing a new feature (multi-PR contributing) -- open an issue describing the feature you want to contribute - - use sub issues for larger, more complex project. 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, you can work off of a fork, with this feat/ branch as the target. -- make a feat/my-new-feature branch that will be long-lived branch -- break your work into smaller issue/PR pairs that target `feat/my-new-feature`, and ask for frequent reviews. -- PR title should be essentially a changelog entry +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 -## CI, linting, style guide -- CI tests, docs, etc, will run on every PR that as `main` as a target. -- pre-commit comment -- rebase or merge, we don't care, but keep your branch up to date with `main` -- SQUASH ALWAYS 🍠 -- [numpy docstrings](https://numpydoc.readthedocs.io/en/latest/format.html), use type hinting as much as is reasonable. -- tests in every PR -- using `precommit` locally: - - pyproject.toml -- any pins to versions in environments etc. need to have a comment explaining why, linking to the related issue, etc. +```yaml +... -## Review process -- In general, push PRs early so that work is visibile, 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. + - 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. -# TODO: ai use disclosure \ No newline at end of file +## 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 From 2503d1c4fc54a295bc0c3110e50bb423e6a102f8 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 14 Oct 2025 14:49:40 -0700 Subject: [PATCH 5/5] remove other md --- .github/CONTRIBUTING.md | 22 ---------------------- 1 file changed, 22 deletions(-) delete mode 100644 .github/CONTRIBUTING.md 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.