From 6c3f5904e9721757fb6f41c550b42c3ef4c4f539 Mon Sep 17 00:00:00 2001 From: Ianna Osborne Date: Tue, 22 Apr 2025 14:15:22 +0200 Subject: [PATCH 1/7] docs: add contributing guide --- CONTRIBUTING.md | 154 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..a5024bf10 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,154 @@ +# Contributing to uproot + +Thank you for your interest in contributing to **uproot**! uproot is a community-driven project, and we welcome contributions of all kinds, including bug reports, feature requests, documentation improvements, and code contributions. + +This guide will help you get started with contributing. + +--- + +## 🚀 Quick Start + +1. **Fork** the repository on GitHub. +2. **Clone** your fork locally: + ```bash + git clone https://github.com/YOUR_USERNAME/uproot.git + cd uproot + ``` + +3. **Set up the development environment**: + + We recommend using a conda environment. You can reproduce the full developer environment with: + + ```bash + conda create -n uproot-py313 python=3.13 + conda activate uproot-py313 + + # Add conda-forge channel and prioritize it + conda config --add channels conda-forge + conda config --set channel_priority strict + + # Install dependencies + conda install xrootd + conda install root + conda install pandas + conda install dask + conda install minio + + # pip-only dependencies + pip install scikit-hep-testdata + pip install rangehttpserver + pip install boost_histogram + pip install hist + pip install dask_awkward + pip install awkward-pandas + pip install pytest-timeout + pip install fsspec-xrootd + + # Run local HTTP server (if needed for test data) + python -m RangeHTTPServer + ``` + +4. **Install Uproot in editable mode**: + ```bash + pip install -e . + ``` + +--- + +## 🌿 Branching and Naming Conventions + +- Always work on a **feature branch**: + ```bash + git checkout -b YOUR_USERNAME/my-cool-feature + ``` +- Use descriptive names, such as: + - `fix_streamer-parsing` + - `feature_custom-interpretation-api` + - `docs_improve-tutorials` + +--- + +## 🎨 Code Style + +- Follow **PEP8** where applicable. +- Use **Black** for automatic formatting: + ```bash + black src tests + ``` +- Use **isort** for import sorting: + ```bash + isort src tests + ``` +- Run **flake8** to check for style issues. + +--- + +## ✅ Running Tests + +Uproot uses **pytest** for testing. + +To run the full test suite: +```bash +python -m pytest tests -ss -vv +``` + +To run a specific test module: +```bash +pytest tests/test_my_module.py +``` + +Some tests may depend on having ROOT or XRootD installed. These are covered in the environment setup. + +--- + +## 🔃 Submitting a Pull Request + +1. Make sure all tests pass and your code is cleanly formatted. +2. Push your changes to your fork: + ```bash + git push origin YOUR_USERNAME/my-cool-feature + ``` +3. Open a pull request (PR) from your fork to the `main` branch of [scikit-hep/uproot](https://github.com/scikit-hep/uproot). +4. Fill in the PR template and explain what you did and why. +5. Be responsive to feedback from reviewers—we’re all here to help! + +--- + +## 🐛 Reporting Bugs + +1. Check if the bug is already reported on the [issue tracker](https://github.com/scikit-hep/uproot/issues). +2. If not, [open a new issue](https://github.com/scikit-hep/uproot/issues/new/choose) and provide: + - A minimal reproducible example + - Expected vs. actual behavior + - Version info (`python -m uproot --version`) + - Any relevant stack trace or logs + +--- + +## 💡 Requesting Features + +1. Search the issues to see if a similar feature has been discussed. +2. If not, open a **Feature Request** issue and describe: + - What problem the feature solves + - A suggested implementation or interface (if applicable) + - Any related prior art in other libraries or experiments + +--- + +## 📚 Improving Documentation + +Documentation lives in the `docs/` folder and is built using **Sphinx**. To build locally: +```bash +cd docs +make html +``` + +You can also suggest improvements to examples, tutorials, and API references. + +--- + +## 🙌 Thanks! + +uproot thrives on its community. Whether you're fixing a typo, contributing a feature, or suggesting a design—you're making a difference! + + From 888ec31b4c3d82512aa48a82ae2be3fa6b498ab4 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 22 Apr 2025 12:16:48 +0000 Subject: [PATCH 2/7] style: pre-commit fixes --- CONTRIBUTING.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a5024bf10..a862adba9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -150,5 +150,3 @@ You can also suggest improvements to examples, tutorials, and API references. ## 🙌 Thanks! uproot thrives on its community. Whether you're fixing a typo, contributing a feature, or suggesting a design—you're making a difference! - - From 57e64cd77df72db41d6913f9cbcda48e5a31743b Mon Sep 17 00:00:00 2001 From: Ianna Osborne Date: Tue, 22 Apr 2025 17:00:03 +0200 Subject: [PATCH 3/7] Update CONTRIBUTING.md Co-authored-by: Andres Rios Tascon --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a862adba9..5d36cb5d2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,7 +11,7 @@ This guide will help you get started with contributing. 1. **Fork** the repository on GitHub. 2. **Clone** your fork locally: ```bash - git clone https://github.com/YOUR_USERNAME/uproot.git + git clone git@github.com:YOUR_USERNAME/uproot5.git cd uproot ``` From 2252d574f9b7ba8fcbd64f15007a8a7aab559be3 Mon Sep 17 00:00:00 2001 From: Ianna Osborne Date: Tue, 22 Apr 2025 17:00:26 +0200 Subject: [PATCH 4/7] Update CONTRIBUTING.md Co-authored-by: Andres Rios Tascon --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5d36cb5d2..b84f437a3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -149,4 +149,4 @@ You can also suggest improvements to examples, tutorials, and API references. ## 🙌 Thanks! -uproot thrives on its community. Whether you're fixing a typo, contributing a feature, or suggesting a design—you're making a difference! +uproot thrives on its community. Whether you're fixing a typo, contributing a feature, or suggesting a design—you're making a difference! From 6badec15e34a98281e8045a74b7594e49ce35257 Mon Sep 17 00:00:00 2001 From: Ianna Osborne Date: Tue, 22 Apr 2025 17:00:42 +0200 Subject: [PATCH 5/7] Update CONTRIBUTING.md Co-authored-by: Andres Rios Tascon --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b84f437a3..46c792484 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -50,7 +50,7 @@ This guide will help you get started with contributing. 4. **Install Uproot in editable mode**: ```bash - pip install -e . + pip install -e ."[dev,test]" ``` --- From 7cbb97e48f2d82d0d3326b7a5e2c27c39811479c Mon Sep 17 00:00:00 2001 From: Ianna Osborne Date: Tue, 22 Apr 2025 17:36:01 +0200 Subject: [PATCH 6/7] use pre-commit --- CONTRIBUTING.md | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 46c792484..bf91684e6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,16 +70,9 @@ This guide will help you get started with contributing. ## 🎨 Code Style -- Follow **PEP8** where applicable. -- Use **Black** for automatic formatting: +- Use **pre-commit** for automatic linting, style issues, and formatting: ```bash - black src tests - ``` -- Use **isort** for import sorting: - ```bash - isort src tests - ``` -- Run **flake8** to check for style issues. + pre-commit run --all --- From 1ed72a1f38e5b97e03434119397aa83855b0f688 Mon Sep 17 00:00:00 2001 From: Ianna Osborne Date: Tue, 22 Apr 2025 17:51:52 +0200 Subject: [PATCH 7/7] build local documentation howto --- CONTRIBUTING.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf91684e6..edddcbe5c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -130,10 +130,19 @@ Some tests may depend on having ROOT or XRootD installed. These are covered in t ## 📚 Improving Documentation -Documentation lives in the `docs/` folder and is built using **Sphinx**. To build locally: +Documentation lives in the `docs-sphinx/` folder and is built using **Sphinx**. To build locally +make sure you have Sphinx and the ReadTheDocs theme installed in your virtualenv: ```bash -cd docs -make html +pip install sphinx sphinx-rtd-theme +``` +Navigate to your docs folder and invoke the Sphinx builder to produce HTML in the _build/html directory: +``` +cd docs-sphinx +sphinx-build -b html . _build/html +``` +Once it finishes, open: +``` +open _build/html/index.html ``` You can also suggest improvements to examples, tutorials, and API references.