docs: Add CONTRIBUTING.md with comprehensive guidelines #170
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
7 tasks
Contributor
Author
|
Hi @florisvb! 👋 This PR adds the CONTRIBUTING.md file as requested in issue #169. I've created comprehensive guidelines that cover: ✅ Development Setup - Step-by-step instructions for setting up the development environment The guidelines are based on the existing project structure and tools. I've made sure to reference the actual tools used in the project (pytest, pylint, GitHub Actions, etc.). I'm open to any feedback or suggestions for improvements. Please let me know if you'd like me to adjust anything! |
Add comprehensive contributing guidelines covering: - Development setup instructions - Code style guidelines (PEP 8, pylint) - Testing guidelines (pytest) - Pull request process - Bug reporting templates - Feature proposal templates - Commit message conventions This addresses issue florisvb#169 and provides clear guidance for new contributors to get started with the project. Fixes florisvb#169
Nimra-Fayaz
force-pushed
the
docs/add-contributing-guidelines
branch
from
7c95e34 to
b03bdaf
Compare
CONTRIBUTING.md
Outdated
| @@ -0,0 +1,393 @@ | |||
| # Contributing to PyNumDiff | |||
|
|
|||
| Thank you for your interest in contributing to PyNumDiff! This document provides guidelines and instructions for contributing to the project. Following these guidelines helps communicate that you respect the time of the developers managing and developing this open-source project. | |||
Collaborator
There was a problem hiding this comment.
lol, I wouldn't emphasize our need for respect. Anyone taking an interest is enough for us. Makes us sound a bit jilted and stiff, although maybe there's some deep truth to that for academics.
CONTRIBUTING.md
Outdated
|
|
||
| ## Code of Conduct | ||
|
|
||
| This project adheres to a code of conduct that all contributors are expected to follow. Please be respectful and constructive in all interactions. |
Collaborator
There was a problem hiding this comment.
Again the emphasis on respect is weird to me.
CONTRIBUTING.md
Outdated
| - [Commit Message Conventions](#commit-message-conventions) | ||
| - [Questions?](#questions) | ||
|
|
||
| ## Code of Conduct |
Collaborator
There was a problem hiding this comment.
I'd nix this whole short subsection.
CONTRIBUTING.md
Outdated
|
|
||
| ## How Can I Contribute? | ||
|
|
||
| ### Reporting Bugs |
Collaborator
There was a problem hiding this comment.
These little stub sections that just link the user to other reporting bugs and suggesting enhancements sections seem redundant to me.
CONTRIBUTING.md
Outdated
|
|
||
| ### Prerequisites | ||
|
|
||
| - Python 3.7 or higher |
Collaborator
There was a problem hiding this comment.
I'd maybe recommend 3.11 or higher.
|
|
||
| 5. **Install the package in development mode**: | ||
| ```bash | ||
| pip install -e . |
Collaborator
There was a problem hiding this comment.
Nice. I like the emphasis on editable installs. They are the way to go.
CONTRIBUTING.md
Outdated
| ### PR Guidelines | ||
|
|
||
| - Keep PRs focused on a single issue or feature | ||
| - Keep PRs reasonably sized (if large, consider breaking into smaller PRs) |
Collaborator
There was a problem hiding this comment.
I do not always do this, but I'm dictator and had a lot I needed to change. Yes, bite sized, more focused chunks are easier to get through review quickly.
CONTRIBUTING.md
Outdated
|
|
||
| ### Commit Message Format | ||
|
|
||
| We follow a conventional commit message format: |
Collaborator
There was a problem hiding this comment.
I haven't been doing this. It's some trouble, and sometimes I just want to commit now. But I do endorse long, descriptive commit messages. Just they can be free-form.
| <footer> | ||
| ``` | ||
|
|
||
| ### Types |
Collaborator
There was a problem hiding this comment.
I don't think we need to be quite this specific. This project isn't so large that we're doing triage on PRs or anything. I'd say this lexicon of types can go away, and we can allow authors to write whatever they want in their commit messages.
CONTRIBUTING.md
Outdated
| - `test`: Adding or updating tests | ||
| - `chore`: Maintenance tasks (dependencies, build config, etc.) | ||
|
|
||
| ### Examples |
Collaborator
There was a problem hiding this comment.
Don't think we need this example.
CONTRIBUTING.md
Outdated
| Updated README with clearer installation steps for Windows users. | ||
| ``` | ||
|
|
||
| ### Guidelines |
Collaborator
There was a problem hiding this comment.
Don't think we need guidelines. I'm mildly anarchic about it.
Owner
|
Thanks Pavel. I agree with almost all of his comments.
I would say that for new community contributors keeping commits small and
writing out notes of what was changed is definitely important. Pavel
embarked on a large scale overhaul that came with unique privileges :)
…On Fri, Nov 14, 2025 at 11:37 AM Pavel Komarov ***@***.***> wrote:
***@***.**** commented on this pull request.
Thanks for the add! It's almost too over detailed in places, so I've added
some comments to suggest ways I think it can be slimmed down.
------------------------------
In CONTRIBUTING.md
<#170 (comment)>:
> +## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [How Can I Contribute?](#how-can-i-contribute)
+- [Development Setup](#development-setup)
+- [Code Style Guidelines](#code-style-guidelines)
+- [Testing Guidelines](#testing-guidelines)
+- [Pull Request Process](#pull-request-process)
+- [Reporting Bugs](#reporting-bugs)
+- [Proposing Features](#proposing-features)
+- [Commit Message Conventions](#commit-message-conventions)
+- [Questions?](#questions)
+
+## Code of Conduct
+
+This project adheres to a code of conduct that all contributors are expected to follow. Please be respectful and constructive in all interactions.
Again the emphasis on respect is weird to me.
------------------------------
In CONTRIBUTING.md
<#170 (comment)>:
> +Thank you for your interest in contributing to PyNumDiff! This document provides guidelines and instructions for contributing to the project. Following these guidelines helps communicate that you respect the time of the developers managing and developing this open-source project.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [How Can I Contribute?](#how-can-i-contribute)
+- [Development Setup](#development-setup)
+- [Code Style Guidelines](#code-style-guidelines)
+- [Testing Guidelines](#testing-guidelines)
+- [Pull Request Process](#pull-request-process)
+- [Reporting Bugs](#reporting-bugs)
+- [Proposing Features](#proposing-features)
+- [Commit Message Conventions](#commit-message-conventions)
+- [Questions?](#questions)
+
+## Code of Conduct
I'd nix this whole short subsection.
------------------------------
In CONTRIBUTING.md
<#170 (comment)>:
> +- [Development Setup](#development-setup)
+- [Code Style Guidelines](#code-style-guidelines)
+- [Testing Guidelines](#testing-guidelines)
+- [Pull Request Process](#pull-request-process)
+- [Reporting Bugs](#reporting-bugs)
+- [Proposing Features](#proposing-features)
+- [Commit Message Conventions](#commit-message-conventions)
+- [Questions?](#questions)
+
+## Code of Conduct
+
+This project adheres to a code of conduct that all contributors are expected to follow. Please be respectful and constructive in all interactions.
+
+## How Can I Contribute?
+
+### Reporting Bugs
These little stub sections that just link the user to other reporting bugs
and suggesting enhancements sections seem redundant to me.
------------------------------
In CONTRIBUTING.md
<#170 (comment)>:
> +
+Have an idea for a new feature or improvement? Please [open an issue](https://github.com/florisvb/PyNumDiff/issues/new) to discuss it. See the [Proposing Features](#proposing-features) section for details.
+
+### Contributing Code
+
+1. Look for issues labeled `good first issue` if you're new to the project
+2. Fork the repository
+3. Create a branch for your changes
+4. Make your changes following our guidelines
+5. Submit a pull request
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.7 or higher
I'd maybe recommend 3.11 or higher.
------------------------------
In CONTRIBUTING.md
<#170 (comment)>:
> +
+4. **Create a virtual environment** (recommended):
+ ```bash
+ # Using venv
+ python -m venv venv
+
+ # Activate on Windows
+ venv\Scripts\activate
+
+ # Activate on macOS/Linux
+ source venv/bin/activate
+ ```
+
+5. **Install the package in development mode**:
+ ```bash
+ pip install -e .
Nice. I like the emphasis on editable installs. They are the way to go.
------------------------------
In CONTRIBUTING.md
<#170 (comment)>:
> + ```bash
+ pip install pytest pylint
+ ```
+
+7. **Verify the installation**:
+ ```bash
+ pytest -s
+ ```
+
+### Project Structure
+
+- `pynumdiff/` - Main source code
+- `examples/` - Jupyter notebook examples
+- `docs/` - Documentation source files
+- `.github/workflows/` - GitHub Actions CI configuration
+- `tests/` - Test files (if applicable)
The tests live in /pynumdiff/tests currently. I'm not strongly attached
to that, but it should probably be reflected accurately here.
------------------------------
In CONTRIBUTING.md
<#170 (comment)>:
> + pytest -s
+ ```
+
+### Project Structure
+
+- `pynumdiff/` - Main source code
+- `examples/` - Jupyter notebook examples
+- `docs/` - Documentation source files
+- `.github/workflows/` - GitHub Actions CI configuration
+- `tests/` - Test files (if applicable)
+
+## Code Style Guidelines
+
+### Python Style Guide
+
+PyNumDiff follows [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guidelines. Here are the key points:
Oh man, I am *definitely* not following PEP 8 lol. I don't know that we
need to emphasize any particular coding style. Just more or less try to
match existing method signatures and docstrings.
------------------------------
In CONTRIBUTING.md
<#170 (comment)>:
> +
+### Project Structure
+
+- `pynumdiff/` - Main source code
+- `examples/` - Jupyter notebook examples
+- `docs/` - Documentation source files
+- `.github/workflows/` - GitHub Actions CI configuration
+- `tests/` - Test files (if applicable)
+
+## Code Style Guidelines
+
+### Python Style Guide
+
+PyNumDiff follows [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guidelines. Here are the key points:
+
+- Use 4 spaces for indentation (no tabs)
I actually prefer tabs but wasn't able to convince @florisvb
<https://github.com/florisvb> yet. #99
<#99>
------------------------------
In CONTRIBUTING.md
<#170 (comment)>:
> +### Project Structure
+
+- `pynumdiff/` - Main source code
+- `examples/` - Jupyter notebook examples
+- `docs/` - Documentation source files
+- `.github/workflows/` - GitHub Actions CI configuration
+- `tests/` - Test files (if applicable)
+
+## Code Style Guidelines
+
+### Python Style Guide
+
+PyNumDiff follows [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guidelines. Here are the key points:
+
+- Use 4 spaces for indentation (no tabs)
+- Maximum line length: 79 characters (soft limit) or 99 characters (hard limit)
I'm pretty sure I use lines that are like 200 characters sometimes lol.
------------------------------
In CONTRIBUTING.md
<#170 (comment)>:
> +
+### Python Style Guide
+
+PyNumDiff follows [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guidelines. Here are the key points:
+
+- Use 4 spaces for indentation (no tabs)
+- Maximum line length: 79 characters (soft limit) or 99 characters (hard limit)
+- Use meaningful variable and function names
+- Follow naming conventions:
+ - Functions and variables: `snake_case`
+ - Classes: `PascalCase`
+ - Constants: `UPPER_SNAKE_CASE`
+
+### Code Quality
+
+The project uses `pylint` for code quality checks. Before submitting a PR:
I haven't been doing this for a while either. But the plan is to submit
this thing to JOSS again, and I think they're more strict about linting, so
I'll have to run it again.
------------------------------
In CONTRIBUTING.md
<#170 (comment)>:
> +### Running Tests
+
+PyNumDiff uses `pytest` for testing. To run tests:
+
+```bash
+# Run all tests
+pytest -s
+
+# Run tests with plots (to visualize method results)
+pytest -s --plot
+
+# Run tests with bounds (to print log error bounds)
+pytest -s --bounds
+```
+
+### Writing Tests
Might be helpful to mention that the test_diff_methods broadly tests for
correctness/ability to actually differentiate, that test_utils contains
tests of miscellaneous stuff like simulations and evaluation metrics and
whatnot, and test_optimize tests the hyperparameter optimization code,
which is its own beast.
------------------------------
In CONTRIBUTING.md
<#170 (comment)>:
> +
+3. **Wait for CI** to run and ensure all checks pass
+
+4. **Respond to feedback** from maintainers and reviewers
+
+5. **Keep your PR up to date** by rebasing on master if needed:
+ ```bash
+ git fetch upstream
+ git rebase upstream/master
+ git push --force-with-lease origin feature/your-feature-name
+ ```
+
+### PR Guidelines
+
+- Keep PRs focused on a single issue or feature
+- Keep PRs reasonably sized (if large, consider breaking into smaller PRs)
I do not always do this, but I'm dictator and had a lot I needed to
change. Yes, bite sized, more focused chunks are easier to get through
review quickly.
------------------------------
In CONTRIBUTING.md
<#170 (comment)>:
> +
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or examples about the feature request here.
+```
+
+## Commit Message Conventions
+
+### Commit Message Format
+
+We follow a conventional commit message format:
I haven't been doing this. It's some trouble, and sometimes I just want to
commit now. But I do endorse long, descriptive commit messages. Just they
can be free-form.
------------------------------
In CONTRIBUTING.md
<#170 (comment)>:
> +
+## Commit Message Conventions
+
+### Commit Message Format
+
+We follow a conventional commit message format:
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Types
I don't think we need to be quite this specific. This project isn't so
large that we're doing triage on PRs or anything. I'd say this lexicon of
types can go away, and we can allow authors to write whatever they want in
their commit messages.
------------------------------
In CONTRIBUTING.md
<#170 (comment)>:
> +<body>
+
+<footer>
+```
+
+### Types
+
+- `feat`: A new feature
+- `fix`: A bug fix
+- `docs`: Documentation only changes
+- `style`: Code style changes (formatting, missing semicolons, etc.)
+- `refactor`: Code refactoring without changing functionality
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks (dependencies, build config, etc.)
+
+### Examples
Don't think we need this example.
------------------------------
In CONTRIBUTING.md
<#170 (comment)>:
> +```
+fix(differentiation): correct boundary condition handling
+
+Fixed an issue where boundary conditions were not properly
+handled for signals with variable step sizes.
+
+Closes #456
+```
+
+```
+docs(readme): update installation instructions
+
+Updated README with clearer installation steps for Windows users.
+```
+
+### Guidelines
Don't think we need guidelines. I'm mildly anarchic about it.
—
Reply to this email directly, view it on GitHub
<#170 (review)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAB4EPFBPS5AO3OGSMHYKR334YVQRAVCNFSM6AAAAACMDA24DCVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTINRWGQ2TQMJWGI>
.
You are receiving this because you were mentioned.Message ID:
***@***.***>
--
Floris van Breugel | http://www.florisvanbreugel.com
Associate Professor of Mechanical Engineering
& Graduate Program for Neuroscience
University of Nevada, Reno
Wildlife and Landscape Photography
Galleries: http://www.ArtInNaturePhotography.com/
Blog: http://www.ArtInNaturePhotography.com/wordpress/
|
- Remove formal language and emphasis on respect - Remove Code of Conduct section - Remove redundant How Can I Contribute stub section - Update Python version requirement to 3.11 - Simplify commit message guidelines to free-form style - Update PR guidelines to be less prescriptive - Relax code style guidelines to focus on matching existing code - Update code quality section to note JOSS submission requirements - Add information about test file organization - Update line length guidelines to reflect actual practice
Contributor
Author
|
Hi @pavelkomarov and @florisvb, I've updated CONTRIBUTING.md based on your feedback. The document is now more concise and less prescriptive, matching the project's current practices. Please let me know if you'd like any other adjustments. Thanks for the feedback. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR adds a comprehensive CONTRIBUTING.md file that provides clear guidelines for new contributors to the PyNumDiff project.
Changes
Benefits
This addresses issue #169.
Checklist