From b4910283523c9228fde45f0d9759c3c8303620b4 Mon Sep 17 00:00:00 2001 From: harryswift01 Date: Thu, 16 Oct 2025 14:18:10 +0100 Subject: [PATCH 1/7] include orcid information for `Harry Swift` within `CITATION.cff` file --- CITATION.cff | 1 + 1 file changed, 1 insertion(+) diff --git a/CITATION.cff b/CITATION.cff index cd54050..8dd0a2e 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -56,6 +56,7 @@ authors: family-names: Swift email: harry.swift@stfc.ac.uk affiliation: 'STFC, Scientific Computing' + orcid: 'https://orcid.org/0009-0007-3323-753X' repository-code: 'https://github.com/CCPBioSim/CodeEntropy' url: 'https://ccpbiosim.github.io/CodeEntropy/' abstract: >- From 7b0e3accf2d23088129ae9c4e6e95da40269fbf1 Mon Sep 17 00:00:00 2001 From: harryswift01 Date: Thu, 16 Oct 2025 14:22:14 +0100 Subject: [PATCH 2/7] update `version` and `date-released` within `CITATION.cff` file --- CITATION.cff | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CITATION.cff b/CITATION.cff index 8dd0a2e..1f50a2c 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -76,5 +76,5 @@ keywords: - biomolecular simulations - protein flexibility license: MIT -version: 0.3.6 -date-released: '2022-07-06' +version: 1.0.3 +date-released: '2025-09-29' From d6bd8a3cde132fa6568e3cd1a20ade2bf5778e55 Mon Sep 17 00:00:00 2001 From: harryswift01 Date: Thu, 16 Oct 2025 14:48:41 +0100 Subject: [PATCH 3/7] updated description within `__init__.py` file --- CodeEntropy/__init__.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/CodeEntropy/__init__.py b/CodeEntropy/__init__.py index 34402c3..06e3df1 100644 --- a/CodeEntropy/__init__.py +++ b/CodeEntropy/__init__.py @@ -1,9 +1,11 @@ """ CodeEntropy -CodeEntropy tool with POSEIDON code integrated to form a complete and generally -applicable set of tools for computing entropy of macromolecular systems from the -forces sampled in a MD simulation. +CodeEntropy is a Python package for computing the configurational entropy of +macromolecular systems using forces sampled from molecular dynamics (MD) simulations. +It implements the multiscale cell correlation method to provide accurate and efficient +entropy estimates, supporting a wide range of applications in molecular simulation +and statistical mechanics. """ __version__ = "1.0.3" From bc7000663d0410e80f651953c03b8eb52a7e9000 Mon Sep 17 00:00:00 2001 From: harryswift01 Date: Thu, 16 Oct 2025 15:18:31 +0100 Subject: [PATCH 4/7] add `CITATION.cff` version update to release workflow: - Update `.github/workflows/release.yaml` to bump `CITATION.cff` version and date-released automatically - Keep version in `__init__.py` and `CITATION.cff` in sync during releases - Fully automated in CI, no manaul edits needed --- .github/workflows/release.yaml | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index d18357f..e23d8ba 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -48,8 +48,16 @@ jobs: - name: checkout uses: actions/checkout@v5.0.0 - - name: Change version in repo - run: sed -i "s/__version__ =.*/__version__ = \"${{ github.event.inputs.version }}\"/g" CodeEntropy/__init__.py + - name: Change version in repo and CITATION.cff + run: | + # Update Python package version + sed -i "s/__version__ =.*/__version__ = \"${{ github.event.inputs.version }}\"/g" CodeEntropy/__init__.py + + # Update CITATION.cff version and date-released + if [ -f CITATION.cff ]; then + sed -i -E "s/^(version:\s*).*/\1${{ github.event.inputs.version }}/" CITATION.cff + sed -i -E "s/^(date-released:\s*).*/\1'$(date -u +%F)'/" CITATION.cff + fi - name: send PR id: pr_id @@ -61,6 +69,7 @@ jobs: body: | Update version - Update the __init__.py with new release + - Update CITATION.cff version & date-released - Auto-generated by [CI] committer: version-updater author: version-updater From d9a1e7bb36fb2f856a56bb8893fa87347d6a1fed Mon Sep 17 00:00:00 2001 From: harryswift01 Date: Wed, 5 Nov 2025 09:31:17 +0000 Subject: [PATCH 5/7] Update `CODE_OF_CONDUCT.md` --- CODE_OF_CONDUCT.md | 151 ++++++++++++++++++++++++++++++--------------- 1 file changed, 101 insertions(+), 50 deletions(-) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 79c3538..729da91 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -2,76 +2,127 @@ ## Our Pledge -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, -body size, disability, ethnicity, gender identity and expression, level of -experience, nationality, personal appearance, race, religion, or sexual -identity and orientation. +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. ## Our Standards -Examples of behavior that contributes to creating a positive environment include: +Examples of behavior that contributes to a positive environment for our +community include: -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community -Examples of unacceptable behavior by participants include: +Examples of unacceptable behavior include: -* The use of sexualized language or imagery and unwelcome sexual attention or advances -* Trolling, insulting/derogatory comments, and personal or political attacks +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks * Public or private harassment -* Publishing others' private information, such as a physical or electronic address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a professional setting - -## Our Responsibilities +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. +## Enforcement Responsibilities -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. -Moreover, project maintainers will strive to offer feedback and advice to -ensure quality and consistency of contributions to the code. Contributions -from outside the group of project maintainers are strongly welcomed but the -final decision as to whether commits are merged into the codebase rests with -the team of project maintainers. +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. ## Scope -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an -appointed representative at an online or offline event. Representation of a -project may be further defined and clarified by project maintainers. +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at 'lpchungaa@gmail.com'. The project team will -review and investigate all complaints, and will respond in a way that it deems -appropriate to the circumstances. The project team is obligated to maintain -confidentiality with regard to the reporter of an incident. Further details of -specific enforcement policies may be posted separately. +reported to the community leaders responsible for enforcement at +ccpbiosim@stfc.ac.uk. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. ## Attribution This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 1.4, available at -[http://contributor-covenant.org/version/1/4][version] +version 2.0, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. \ No newline at end of file From 43a65124ab896db6420453f041e3689aa6c4afb4 Mon Sep 17 00:00:00 2001 From: harryswift01 Date: Wed, 5 Nov 2025 10:01:04 +0000 Subject: [PATCH 6/7] update `CONTRIBUTING.md` --- .github/CONTRIBUTING.md | 185 ++++++++++++++++++++++++++++++++-------- 1 file changed, 150 insertions(+), 35 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 0b59544..ba588b0 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,42 +1,157 @@ -# How to contribute -We welcome contributions from external contributors, and this document -describes how to merge code changes into this CodeEntropy. +# Contributing to CodeEntropy + +We welcome contributions from the community to improve and extend CodeEntropy. This guide outlines how to get started, make changes, and submit them for review. + +--- ## Getting Started -* Make sure you have a [GitHub account](https://github.com/signup/free). -* [Fork](https://help.github.com/articles/fork-a-repo/) this repository on GitHub. -* On your local machine, - [clone](https://help.github.com/articles/cloning-a-repository/) your fork of - the repository. +1. **Create a GitHub account**: [Sign up here](https://github.com/signup/free). +2. **Fork the repository**: [How to fork](https://help.github.com/articles/fork-a-repo/). +3. **Clone your fork locally**: + ```bash + git clone https://github.com/YOUR_USERNAME/CodeEntropy.git + cd CodeEntropy + ``` + +4. **Create a virtual environment**: + ```bash + python -m venv codeentropy-dev + source codeentropy-dev/bin/activate # Linux/macOS + codeentropy-dev\Scripts\activate # Windows + ``` + +5. **Install development dependencies**: + ```bash + pip install -e ".[testing,docs,pre-commit]" + pre-commit install + ``` + +--- ## Making Changes -* Add some really awesome code to your local fork. It's usually a [good - idea](http://blog.jasonmeridth.com/posts/do-not-issue-pull-requests-from-your-master-branch/) - to make changes on a - [branch](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/) - with the branch name relating to the feature you are going to add. -* When you are ready for others to examine and comment on your new feature, - navigate to your fork of CodeEntropy on GitHub and open a [pull - request](https://help.github.com/articles/using-pull-requests/) (PR). Note that - after you launch a PR from one of your fork's branches, all - subsequent commits to that branch will be added to the open pull request - automatically. Each commit added to the PR will be validated for - mergability, compilation and test suite compliance; the results of these tests - will be visible on the PR page. -* If you're providing a new feature, you must add test cases and documentation. -* When the code is ready to go, make sure you run the test suite using pytest. -* When you're ready to be considered for merging, check the "Ready to go" - box on the PR page to let the CodeEntropy devs know that the changes are complete. - The code will not be merged until this box is checked, the continuous - integration returns checkmarks, - and multiple core developers give "Approved" reviews. - -# Additional Resources - -* [General GitHub documentation](https://help.github.com/) -* [PR best practices](http://codeinthehole.com/writing/pull-requests-and-other-good-practices-for-teams-using-github/) -* [A guide to contributing to software packages](http://www.contribution-guide.org) -* [Thinkful PR example](http://www.thinkful.com/learn/github-pull-request-tutorial/#Time-to-Submit-Your-First-PR) +- **Use a feature branch**: + ```bash + git checkout -b 123-fix-levels + ``` + You cannot commit directly to `main` as this is a protected branch. + +- **Add your code**, documentation, and tests. All new features must include: + - Unit tests + - Documentation updates + - Compliance with coding standards + +- **Run tests**: + ```bash + pytest -v + pytest --cov CodeEntropy --cov-report=term-missing + ``` + +- **Run pre-commit checks**: + These ensure formatting, linting, and basic validations. + ```bash + pre-commit run --all-files + ``` + +--- + +## Submitting a Pull Request (PR) + +1. Push your branch to GitHub. +2. Open a [pull request](https://help.github.com/articles/using-pull-requests/). +3. Use the templated Pull Request template to fill out: + - A summary of what the PR is doing + - List all the changes that the PR is proposing + - Add how these changes will impact the repository +4. Ensure: + - All tests pass + - Pre-commit checks pass + - Documentation is updated + +5. Your PR will be reviewed by core developers. At least one approval is required before merging. + +--- + +## Running Tests + +- Full suite: + ```bash + pytest -v + ``` +- With coverage: + ```bash + pytest --cov CodeEntropy --cov-report=term-missing + ``` +- Specific module: + ```bash + pytest CodeEntropy/tests/test_CodeEntropy/test_levels.py + ``` +- Specific test: + ```bash + pytest CodeEntropy/tests/test_CodeEntropy/test_levels.py::test_select_levels + ``` + +--- + +## Coding Standards + +We use **pre-commit hooks** to enforce style and quality: + +- **Black** for formatting +- **Isort** for import sorting +- **Flake8** for linting +- **Pre-commit-hooks** for: + - Large file detection + - AST validity + - Merge conflict detection + - YAML/TOML syntax checks + +--- + +## Continuous Integration (CI) + +All PRs trigger GitHub Actions to: + +- Run tests +- Check style +- Build documentation +- Validate versioning + +--- + +## Building Documentation + +Build locally: +```bash +cd docs +make html +``` + +View in browser: +``` +docs/build/html/index.html +``` + +Edit docs in: +- `docs/science.rst` +- `docs/developer_guide.rst` + +--- + +## Reporting Issues + +Found a bug or want a feature? + +1. Open an issue on GitHub. +2. Include a clear description and input files if relevant. + +--- + +## Additional Resources + +- [GitHub Docs](https://help.github.com/) +- [PR Best Practices](http://codeinthehole.com/writing/pull-requests-and-other-good-practices-for-teams-using-github/) +- [Contribution Guide](http://www.contribution-guide.org) +- [Thinkful PR Tutorial](http://www.thinkful.com/learn/github-pull-request-tutorial/#Time-to-Submit-Your-First-PR) From ef4ed05ba6260d54e477661d0988076ee3165f72 Mon Sep 17 00:00:00 2001 From: Swift Date: Wed, 5 Nov 2025 12:53:26 +0000 Subject: [PATCH 7/7] refined `CONTRIBUTING.md` avoiding duplication with the docs --- .github/CONTRIBUTING.md | 164 +++++++++------------------------------- 1 file changed, 36 insertions(+), 128 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index ba588b0..5b23339 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,157 +1,65 @@ - # Contributing to CodeEntropy -We welcome contributions from the community to improve and extend CodeEntropy. This guide outlines how to get started, make changes, and submit them for review. - ---- +Thank you for your interest in contributing to **CodeEntropy**! -## Getting Started +We’re excited to collaborate with developers, researchers, and community members to make CodeEntropy better for everyone. -1. **Create a GitHub account**: [Sign up here](https://github.com/signup/free). -2. **Fork the repository**: [How to fork](https://help.github.com/articles/fork-a-repo/). -3. **Clone your fork locally**: - ```bash - git clone https://github.com/YOUR_USERNAME/CodeEntropy.git - cd CodeEntropy - ``` - -4. **Create a virtual environment**: - ```bash - python -m venv codeentropy-dev - source codeentropy-dev/bin/activate # Linux/macOS - codeentropy-dev\Scripts\activate # Windows - ``` - -5. **Install development dependencies**: - ```bash - pip install -e ".[testing,docs,pre-commit]" - pre-commit install - ``` +This guide explains how to set up your environment, make changes, and submit them for review. Whether you’re fixing a bug, improving documentation, or adding new features, every contribution makes a difference. --- -## Making Changes - -- **Use a feature branch**: - ```bash - git checkout -b 123-fix-levels - ``` - You cannot commit directly to `main` as this is a protected branch. - -- **Add your code**, documentation, and tests. All new features must include: - - Unit tests - - Documentation updates - - Compliance with coding standards +## Getting Started -- **Run tests**: - ```bash - pytest -v - pytest --cov CodeEntropy --cov-report=term-missing - ``` +Before contributing, please review the [Developer Guide](https://codeentropy.readthedocs.io/en/latest/developer_guide.html). +It covers CodeEntropy’s architecture, setup instructions, and contribution workflow. -- **Run pre-commit checks**: - These ensure formatting, linting, and basic validations. - ```bash - pre-commit run --all-files - ``` +If you’re new to the project, we also recommend: +- Reading the [README](../README.md) for an overview and installation details. +- Checking open [issues](https://github.com/CCPBioSim/CodeEntropy/issues) labeled **good first issue** to find beginner-friendly tasks. --- ## Submitting a Pull Request (PR) -1. Push your branch to GitHub. -2. Open a [pull request](https://help.github.com/articles/using-pull-requests/). -3. Use the templated Pull Request template to fill out: - - A summary of what the PR is doing - - List all the changes that the PR is proposing - - Add how these changes will impact the repository -4. Ensure: - - All tests pass - - Pre-commit checks pass - - Documentation is updated - -5. Your PR will be reviewed by core developers. At least one approval is required before merging. - ---- - -## Running Tests - -- Full suite: - ```bash - pytest -v - ``` -- With coverage: - ```bash - pytest --cov CodeEntropy --cov-report=term-missing - ``` -- Specific module: - ```bash - pytest CodeEntropy/tests/test_CodeEntropy/test_levels.py - ``` -- Specific test: - ```bash - pytest CodeEntropy/tests/test_CodeEntropy/test_levels.py::test_select_levels - ``` - ---- - -## Coding Standards +When you’re ready to submit your work: -We use **pre-commit hooks** to enforce style and quality: +1. **Push your branch** to GitHub. +2. **Open a [pull request](https://help.github.com/articles/using-pull-requests/)** against the `main` branch. +3. **Fill out the PR template**, including: + - A concise summary of what your PR does + - A list of all changes introduced + - Details on how these changes affect the repository (features, tests, documentation, etc.) +4. **Verify before submission**: + - All tests pass + - Pre-commit checks succeed + - Documentation is updated where applicable +5. **Review process**: + - Your PR will be reviewed by the core development team. + - At least **one approval** is required before merging. -- **Black** for formatting -- **Isort** for import sorting -- **Flake8** for linting -- **Pre-commit-hooks** for: - - Large file detection - - AST validity - - Merge conflict detection - - YAML/TOML syntax checks +We aim to provide constructive feedback quickly and appreciate your patience during the review process. --- -## Continuous Integration (CI) - -All PRs trigger GitHub Actions to: - -- Run tests -- Check style -- Build documentation -- Validate versioning - ---- - -## Building Documentation +## Reporting Issues -Build locally: -```bash -cd docs -make html -``` +Found a bug or have a feature request? -View in browser: -``` -docs/build/html/index.html -``` +1. **Open a new issue** on GitHub. +2. Provide a **clear and descriptive title**. +3. Include: + - Steps to reproduce the issue (if applicable) + - Expected vs. actual behavior + - Relevant logs, screenshots, or input files -Edit docs in: -- `docs/science.rst` -- `docs/developer_guide.rst` +Well-documented issues help us address problems faster and keep CodeEntropy stable and robust. --- -## Reporting Issues - -Found a bug or want a feature? +## Additional Resources -1. Open an issue on GitHub. -2. Include a clear description and input files if relevant. +- [GitHub Docs](https://help.github.com/) --- -## Additional Resources - -- [GitHub Docs](https://help.github.com/) -- [PR Best Practices](http://codeinthehole.com/writing/pull-requests-and-other-good-practices-for-teams-using-github/) -- [Contribution Guide](http://www.contribution-guide.org) -- [Thinkful PR Tutorial](http://www.thinkful.com/learn/github-pull-request-tutorial/#Time-to-Submit-Your-First-PR) +Thank you for helping improve **CodeEntropy**, your contributions make open source stronger!