diff --git a/.copier-answers.yml b/.copier-answers.yml index 2ed76aa..9401915 100644 --- a/.copier-answers.yml +++ b/.copier-answers.yml @@ -1,6 +1,6 @@ # WARNING: Do not edit this file manually. # Any changes will be overwritten by Copier. -_commit: v0.5.0-11-g88c9a0e +_commit: v0.7.0 _src_path: gh:easyscience/templates lib_docs_url: https://easyscience.github.io/utils lib_doi: 10.5281/zenodo.18163581 diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 70cc831..f45c1fa 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -14,16 +14,16 @@ name: Docs build and deployment on: - # Trigger the workflow on pull request - pull_request: - # Selected branches - branches: [master, main, develop] # Trigger the workflow on push push: # Selected branches - branches: [master, main, develop] + branches: [develop] # master and main are already verified in PR # Runs on creating a new tag starting with 'v', e.g. 'v1.0.3' tags: ['v*'] + # Trigger the workflow on pull request + pull_request: + # Selected branches + branches: [master, main, develop] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml index b11f909..52e75b4 100644 --- a/.github/workflows/quality.yml +++ b/.github/workflows/quality.yml @@ -10,8 +10,7 @@ name: Code quality checks on: # Trigger the workflow on push push: - # Every branch - branches: ['**'] + branches-ignore: [master, main] # Already verified in PR # Do not run this workflow on creating a new tag starting with # 'v', e.g. 'v1.0.3' (see publish-pypi.yml) tags-ignore: ['v*'] diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml index 4bbb91f..9b34ccc 100644 --- a/.github/workflows/security.yml +++ b/.github/workflows/security.yml @@ -1,40 +1,93 @@ -# Integrates a collection of open source static analysis tools with -# GitHub code scanning. -# https://github.com/github/ossar-action +# Code scanning (CodeQL) for vulnerabilities and insecure coding patterns. +# +# What this workflow does +# - Runs GitHub CodeQL analysis and uploads results to your repository's Security tab. +# - Triggers on PRs (so findings appear as PR checks) and on pushes to `develop`. +# - Runs on a weekly schedule. +# +# Where to find results on GitHub +# - Repository → Security → Code scanning alerts +# (You can filter by tool = CodeQL and by branch.) +# +# Where to configure on GitHub +# - Repository → Settings → Advanced Security +# Enable "GitHub Advanced Security" (if available) and configure CodeQL there. +# - Repository → Security → Code scanning alerts +# This page shows findings produced by this workflow. +# +# Notes about the scheduled run +# - Scheduled workflows are triggered from the repository's *default branch*. +# If your default branch is `master` but you want the scheduled scan to analyze +# `develop`, this workflow checks out `develop` explicitly for scheduled runs. +# +# References +# - CodeQL Action: https://github.com/github/codeql-action +# - Advanced setup docs: https://docs.github.com/en/code-security/code-scanning -name: Security scans +name: Security scans with CodeQL on: - # Trigger the workflow on pull request + # Run on pull requests so results show up as PR checks and code + # scanning alerts. pull_request: + branches: [master, main, develop] - # Allows you to run this workflow manually from the Actions tab - workflow_dispatch: + # Run on pushes (e.g., after merging PRs). + push: + branches: [master, main, develop] + + # Run weekly. (Cron is in UTC.) + schedule: + - cron: '0 3 * * 1' + +permissions: + contents: read + security-events: write jobs: - scan-security-ossar: - # OSSAR runs on windows-latest. - # ubuntu-latest and macos-latest support coming soon - runs-on: windows-latest + codeql: + name: Code scanning + runs-on: ubuntu-latest + + strategy: + fail-fast: false + matrix: + # Keep this list tight to avoid noise and speed up runs. + language: [python, actions] steps: + # Scheduled workflows run from the default branch. + # We explicitly analyze `develop` on the schedule to keep the scan + # focused on the active dev branch. + - name: Checkout repository (scheduled → develop) + if: ${{ github.event_name == 'schedule' }} + uses: actions/checkout@v5 + with: + ref: develop + - name: Checkout repository + if: ${{ github.event_name != 'schedule' }} uses: actions/checkout@v5 + + - name: Initialize CodeQL + uses: github/codeql-action/init@v4 with: - # We must fetch at least the immediate parents so that if this is - # a pull request then we can checkout the head. - fetch-depth: 2 + languages: ${{ matrix.language }} - # If this run was triggered by a pull request event, then checkout - # the head of the pull request instead of the merge commit. - - run: git checkout HEAD^2 - if: ${{ github.event_name == 'pull_request' }} + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v4 - - name: Run open source static analysis tools - uses: github/ossar-action@main - id: ossar + print-link: + name: Print results link + runs-on: ubuntu-latest - - name: Upload results to Security tab - uses: github/codeql-action/upload-sarif@v3 - with: - sarif_file: ${{ steps.ossar.outputs.sarifFile }} + needs: codeql + permissions: {} # no special perms needed just to print links + + steps: + - name: Add Code Scanning link to job summary + run: | + echo "## 🔎 CodeQL Results" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "View Code Scanning alerts here:" >> $GITHUB_STEP_SUMMARY + echo "${{ github.server_url }}/${{ github.repository }}/security/code-scanning" >> $GITHUB_STEP_SUMMARY diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 2766ddd..7ba46ae 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -20,8 +20,7 @@ name: Code and package tests on: # Trigger the workflow on push push: - # Every branch - branches: ['**'] + branches-ignore: [master, main] # Already verified in PR # But do not run this workflow on creating a new tag starting with # 'v', e.g. 'v1.0.3' (see publish-pypi.yml) tags-ignore: ['v*'] diff --git a/.github/workflows/tutorial-tests.yml b/.github/workflows/tutorial-tests.yml index 5599884..369150c 100644 --- a/.github/workflows/tutorial-tests.yml +++ b/.github/workflows/tutorial-tests.yml @@ -4,7 +4,7 @@ on: # Trigger the workflow on push push: # Selected branches - branches: [master, main, develop] + branches: [develop] # master and main are already verified in PR # Trigger the workflow on pull request pull_request: branches: ['**'] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c73074a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,388 @@ +# Contributing to EasyUtilities + +Thank you for your interest in contributing to **EasyUtilities**! + +This guide explains how to: + +- Report issues +- Contribute code +- Improve documentation +- Suggest enhancements +- Interact with the EasyScience community + +Whether you are an experienced developer or contributing for the first +time, this document walks you through the entire process step by step. + +Please make sure you follow the EasyScience organization-wide +[Code of Conduct](https://github.com/easyscience/.github/blob/master/CODE_OF_CONDUCT.md). + +--- + +## How to Interact With This Project + +If you are not planning to modify the code, you may want to: + +- 🐞 Report a bug — see [Reporting Issues](#11-reporting-issues) +- 🛡 Report a security issue — see + [Security Issues](#12-security-issues) +- 💬 Ask a question or start a discussion at + [Project Discussions](https://github.com/easyscience/utils/discussions) + +If you plan to contribute code or documentation, continue below. + +--- + +## 1. Understanding the Development Model + +Before you start coding, it is important to understand how development +works in this project. + +### Branching Strategy + +We use the following branches: + +- `master` — stable releases only +- `develop` — active development branch +- Short-lived branches — one branch per contribution + +All normal contributions must target the `develop` branch. + +This means: + +- Do **not** open Pull Requests against `master` +- Always create your branch from `develop` +- Always target `develop` when opening a Pull Request + +See ADR easyscience/.github#12 for full details on the branching +strategy. + +--- + +## 2. Getting the Code + +### 2.1. If You Are an External Contributor + +If you are not a core maintainer of this repository, follow these steps. + +1. Open the repository page: `https://github.com/easyscience/utils` + +2. Click the **Fork** button (top-right corner). This creates your own + copy of the repository. + +3. Clone your fork locally: + + ```bash + git clone https://github.com//utils.git + cd utils + ``` + +4. Add the original repository as `upstream`: + + ```bash + git remote add upstream https://github.com/easyscience/utils.git + ``` + +5. Switch to the `develop` branch and update it: + + ```bash + git fetch upstream + git checkout develop + git pull upstream develop + ``` + +If you have contributed before, make sure your local `develop` branch is +up to date before starting new work. You can update it with: + +```bash +git fetch upstream +git pull upstream develop +``` + +This ensures you are working on the latest version of the project. + +### 2.2. If You Are a Core Team Member + +Core team members do not need to fork the repository. You can create a +new branch directly from `develop`, but the rest of the workflow remains +the same. + +--- + +## 3. Setting Up the Development Environment + +You need: + +- Git +- Pixi + +EasyScience projects use **Pixi** to manage the development environment. + +To install Pixi, follow the official instructions: +https://pixi.prefix.dev/latest/installation/ + +You do **not** need to manually install Python. Pixi automatically: + +- Creates the correct Python environment +- Installs all required dependencies +- Installs development tools (linters, formatters, test tools) + +Set up the environment: + +```bash +pixi install +pixi run post-install +``` + +After this step, your development environment is ready. + +See ADR easyscience/.github#63 for more details about this decision. + +--- + +## 4. Creating a Branch + +Never work directly on `develop`. + +Create a new branch: + +```bash +git checkout -b my-change +``` + +Use a clear and descriptive name, for example: + +- `improve-solver-speed` +- `fix-boundary-condition` +- `add-tutorial-example` + +Clear branch names make reviews and history easier to understand. + +--- + +## 5. Implementing Your Changes + +While developing: + +- Make small, logical commits +- Write clear and descriptive commit messages +- Follow the Google docstring convention +- Add or update unit tests if behavior changes + +Example: + +```bash +git add . +git commit -m "Improve performance of time integrator for large systems" +``` + +Run tests locally: + +```bash +pixi run unit-tests +``` + +Running tests frequently is strongly recommended. + +--- + +## 6. Code Quality Checks + +Before opening a Pull Request, always run: + +```bash +pixi run check +``` + +This command runs: + +- Formatting checks +- Linting +- Docstring validation +- Notebook checks +- Unit tests +- Other project validations + +A successful run should look like this: + +```bash +pixi run pyproject-check...................................Passed +pixi run py-lint-check.....................................Passed +pixi run py-format-check...................................Passed +pixi run nonpy-format-check................................Passed +pixi run docs-format-check.................................Passed +pixi run notebook-format-check.............................Passed +pixi run unit-tests........................................Passed +``` + +If something fails, read the error message carefully and fix the issue. + +You can run individual checks, for example: + +```bash +pixi run py-lint-check +``` + +Some formatting issues can be fixed automatically: + +```bash +pixi run fix +``` + +If everything is correctly formatted, you will see: + +```text +✅ All code auto-formatting steps have been applied. +``` + +This indicates that the auto-formatting pipeline completed successfully. +If you do not see this message and no error messages appear, try running +the command again. + +If errors are reported, resolve them and re-run: + +```bash +pixi run check +``` + +All checks must pass before your Pull Request can be merged. + +If you are unsure how to fix an issue, ask for help in your Pull Request +discussion. + +--- + +## 7. Opening a Pull Request + +Push your branch: + +```bash +git push origin my-change +``` + +On GitHub: + +- Click **Compare & Pull Request** +- Ensure the base branch is `develop` +- Write a clear and concise title +- Add a description explaining what changed and why +- Add the required `[scope]` label + +### Pull Request Title + +The PR title appears in release notes and changelogs. It should be +concise and informative. + +Good examples: + +- Improve performance of time integrator for large systems +- Fix incorrect boundary condition handling in solver +- Add adaptive step-size control to ODE solver +- Add tutorial for custom model configuration +- Refactor solver API for improved readability + +### Required `[scope]` Label + +Each Pull Request must include one `[scope]` label: + +| Label | Description | +| ----------------------- | ----------------------------------------------------------------------- | +| `[scope] bug` | Bug report or fix (major.minor.**PATCH**) | +| `[scope] documentation` | Documentation-only changes (major.minor.patch.**POST**) | +| `[scope] enhancement` | Adds or improves features (major.**MINOR**.patch) | +| `[scope] maintenance` | Code/tooling cleanup without feature or bug fix (major.minor.**PATCH**) | +| `[scope] significant` | Breaking or major changes (**MAJOR**.minor.patch) | + +See ADR easyscience/.github#33 for full versioning rules. + +--- + +## 8. Continuous Integration (CI) + +After opening a Pull Request: + +- Automated checks run automatically +- You will see green checkmarks or red crosses + +If checks fail: + +1. Open the failing check +2. Read the logs +3. Fix the issue locally +4. Run `pixi run check` +5. Push your changes + +The Pull Request updates automatically. + +--- + +## 9. Code Review + +All Pull Requests are reviewed by at least one core team member. + +Code review is collaborative and aims to improve quality. + +Do not take comments personally — they are meant to help. + +To update your PR: + +```bash +git add . +git commit -m "Address review comments" +git push +``` + +--- + +## 10. Documentation Contributions + +If your change affects users, update the documentation. + +This may include: + +- API documentation +- Examples +- Tutorials +- Jupyter notebooks + +Preview documentation locally: + +```bash +pixi run docs-serve +``` + +Open the URL shown in the terminal to review your changes. + +--- + +## 11. Reporting Issues + +If you find a bug but do not want to fix it: + +- Search existing issues first +- Provide clear reproduction steps +- Include logs and environment details + +Clear issue reports help maintainers significantly. + +--- + +## 12. Security Issues + +Do **not** report security vulnerabilities publicly. + +If you discover a potential vulnerability, contact the maintainers +privately. + +--- + +## 13. Releases + +Releases are created by merging `develop` into `master`. + +Once your contribution is merged into `develop`, it will be included in +the next stable release. + +--- + +Thank you for contributing to EasyUtilities and the EasyScience +ecosystem! diff --git a/README.md b/README.md index e28ebcc..2f2caec 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,8 @@ functions used across the EasyScience framework. ## Useful Links +### 📚 For Users + - 📖 [Documentation](https://easyscience.github.io/utils/latest) - 🚀 [Getting Started](https://easyscience.github.io/utils/latest/introduction) @@ -26,10 +28,18 @@ functions used across the EasyScience framework. [Get in Touch](https://easyscience.github.io/utils/latest/introduction/#get-in-touch) - 🧾 [Citation](https://easyscience.github.io/utils/latest/introduction/#citation) + +### 🤝 For Contributors + - 🤝 - [Contributing](https://easyscience.github.io/utils/latest/introduction/#contributing) + [Contributing Guide](https://github.com/easyscience/utils/blob/master/CONTRIBUTING.md) +- 🛡 + [Code of Conduct](https://github.com/easyscience/.github/blob/master/CODE_OF_CONDUCT.md) - 🐞 [Issue Tracker](https://github.com/easyscience/utils/issues) - 💡 [Discussions](https://github.com/easyscience/utils/discussions) - 🧑‍💻 [Source Code](https://github.com/easyscience/utils) + +### ⚖️ Project Information + - ⚖️ [License](https://raw.githubusercontent.com/easyscience/utils/refs/heads/master/LICENSE) diff --git a/docs/docs/index.md b/docs/docs/index.md index 2f0f0bc..9b68c5e 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -10,12 +10,6 @@ Here is a brief overview of the main documentation sections: - [:material-cog-box: Installation & Setup](installation-and-setup/index.md) – Guides users through system requirements, environment configuration, and the installation process. -- [:material-book-open-variant: User Guide](user-guide/index.md) – - Covers core concepts, key terminology, workflow steps, and essential - parameters for effective use of EasyUtilities. -- [:material-school: Tutorials](tutorials/index.md) – Offers practical, - step-by-step examples demonstrating common workflows and data analysis - tasks. - [:material-code-braces-box: API Reference](api-reference/index.md) – An auto-generated reference detailing the available functions and modules in EasyUtilities. diff --git a/docs/docs/installation-and-setup/index.md b/docs/docs/installation-and-setup/index.md index efc47d0..be6aefb 100644 --- a/docs/docs/installation-and-setup/index.md +++ b/docs/docs/installation-and-setup/index.md @@ -95,20 +95,8 @@ This section describes the simplest way to set up EasyUtilities using ## Classical Installation This section describes how to install EasyUtilities using the -traditional method with **pip**. This approach is more flexible and -suitable for users familiar with Python package management and virtual -environments. - -!!! warning - - Currently, classical installation doesn't allow installing the - GNU Scientific Library (GSL) dependency automatically. As a result, - the calculation engine **pdffit2** will not be available. To make it - work, ensure that GSL is installed on your system. - - Alternatively, consider using the **Pixi installation method** described - in the [Installing with Pixi](#installing-with-pixi) section, which - handles GSL installation automatically. +traditional method with **pip**. It is assumed that you are familiar +with Python package management and virtual environments. ### Environment Setup optional { #environment-setup data-toc-label="Environment Setup" } @@ -222,76 +210,3 @@ To include extra dependencies (e.g., dev): ```txt pip install 'easyutilities[dev] @ git+https://github.com/easyscience/utils@develop' ``` - -## How to Run Tutorials - -EasyUtilities includes a collection of **Jupyter Notebook examples** -that demonstrate key functionality. These tutorials serve as -**step-by-step guides** to help users understand the data analysis -workflow. They are available as **static HTML pages** in the -[:material-school: Tutorials](../tutorials/index.md) section. - -In the next sections, we explain how to set up Jupyter and run the -tutorials interactively in two different ways: locally or online via -Google Colab. - -If you decide to run the tutorials locally, you need to download them -first. This can be done individually via the :material-download: -**Download Notebook** button available on each tutorial page, or all at -once using the command line, as shown below. - -### Run Tutorials Locally with Pixi recommended { #running-with-pixi data-toc-label="Run Tutorials Locally with Pixi" } - -- Navigate to your existing Pixi project, created as described in the - [Installing with Pixi](#installing-with-pixi) section. -- Add JupyterLab and the Pixi kernel for Jupyter: - ```txt - pixi add --pypi jupyterlab pixi-kernel - ``` -- Download all the EasyUtilities tutorials to the `tutorials/` - directory: - ```txt - pixi run easyutilities download-all-tutorials - ``` -- Start JupyterLab in the `tutorials/` directory to access the - notebooks: - ```txt - pixi run jupyter lab tutorials/ - ``` -- Your web browser should open automatically. Click on one of the - `*.ipynb` files and select the `Python (Pixi)` kernel to get started. - -### Classical Run Tutorials Locally - -- Install Jupyter Notebook and IPython kernel: - ```txt - pip install notebook ipykernel - ``` -- Add the virtual environment as a Jupyter kernel: - ```txt - python -m ipykernel install --user --name=venv --display-name "EasyUtilities Python kernel" - ``` -- Download all the EasyUtilities tutorials to the `tutorials/` - directory: - ```txt - python -m easyutilities download-all-tutorials - ``` -- Launch the Jupyter Notebook server (opens browser automatically at - `http://localhost:8888/`): - ```txt - jupyter notebook tutorials/ - ``` -- Open one of the `*.ipynb` files and select the - `EasyUtilities Python kernel` to get started. - -### Run Tutorials via Google Colab - -**Google Colab** lets you run Jupyter Notebooks in the cloud without any -local installation. This is the fastest way to start experimenting with -EasyUtilities. - -- Ensure you have a **Google account**. -- Go to the **[:material-school: Tutorials](../tutorials/index.md)** - section. -- Click the :google-colab: **Open in Google Colab** button on any - tutorial. diff --git a/docs/docs/introduction/index.md b/docs/docs/introduction/index.md index 0a30330..5e2a070 100644 --- a/docs/docs/introduction/index.md +++ b/docs/docs/introduction/index.md @@ -44,22 +44,23 @@ BibTeX, JSON) are available on the ## Contributing -We welcome contributions from the community! **EasyUtilities** is -intended to be a community-driven, open-source project supported by a -diverse group of contributors. +We welcome contributions of any kind! + +**EasyUtilities** is intended to be a community-driven, open-source +project supported by a diverse group of contributors. The project is maintained by the [European Spallation Source (ESS)](https://ess.eu). -To contribute, see our +If you would like to report a bug or request a new feature, please use +the [GitHub Issue Tracker](https://github.com/easyscience/utils/issues) +(A free GitHub account is required.) + +To contribute code, documentation, or tests, please see our [:material-account-plus: Contributing Guidelines](https://github.com/easyscience/utils/blob/master/CONTRIBUTING.md) -on GitHub. +for detailed development instructions. ## Get in Touch -For general questions or feedback, contact us at +For general questions or feedback, please contact us at [support@easyscience.org](mailto:support@easyscience.org). - -To report bugs or request features, please use the -[GitHub Issue Tracker](https://github.com/easyscience/utils/issues) -(free registration required). diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index be88fea..0857926 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -164,12 +164,6 @@ nav: - Introduction: introduction/index.md - Installation & Setup: - Installation & Setup: installation-and-setup/index.md - - User Guide: - - User Guide: user-guide/index.md - - Tutorials: - - Tutorials: tutorials/index.md - - Getting Started: - - Dummy tutorial: tutorials/tutorial.ipynb - API Reference: - API Reference: api-reference/index.md - environment: api-reference/environment.md diff --git a/pixi.lock b/pixi.lock index fd85fc4..e29da21 100644 --- a/pixi.lock +++ b/pixi.lock @@ -5,6 +5,8 @@ environments: - url: https://conda.anaconda.org/conda-forge/ indexes: - https://pypi.org/simple + options: + pypi-prerelease-mode: if-necessary-or-explicit packages: linux-64: - conda: https://conda.anaconda.org/conda-forge/linux-64/_openmp_mutex-4.5-20_gnu.conda @@ -846,6 +848,8 @@ environments: - url: https://conda.anaconda.org/conda-forge/ indexes: - https://pypi.org/simple + options: + pypi-prerelease-mode: if-necessary-or-explicit packages: linux-64: - conda: https://conda.anaconda.org/conda-forge/linux-64/_openmp_mutex-4.5-20_gnu.conda @@ -1685,6 +1689,8 @@ environments: - url: https://conda.anaconda.org/conda-forge/ indexes: - https://pypi.org/simple + options: + pypi-prerelease-mode: if-necessary-or-explicit packages: linux-64: - conda: https://conda.anaconda.org/conda-forge/linux-64/_openmp_mutex-4.5-20_gnu.conda @@ -3053,7 +3059,7 @@ packages: requires_python: '>=3.5' - pypi: ./ name: easyutilities - version: 0.1.1+dev21 + version: 0.2.0+devdirty3 sha256: 85cc3e3a50e3c8be6e2aeaf80a2f7b3ad8c222996c9caec2ad9d9995300b17e9 requires_dist: - darkdetect @@ -3091,7 +3097,6 @@ packages: - validate-pyproject[all] ; extra == 'dev' - versioningit ; extra == 'dev' requires_python: '>=3.11' - editable: true - pypi: https://files.pythonhosted.org/packages/ab/84/02fc1827e8cdded4aa65baef11296a9bbe595c474f0d6d758af082d849fd/execnet-2.1.2-py3-none-any.whl name: execnet version: 2.1.2