Skip to content

Commit 3c89776

Browse files
pavelkomarovpavelkomarov
authored
Merge pull request #170 from Nimra-Fayaz/docs/add-contributing-guidelines
docs: Add CONTRIBUTING.md with comprehensive guidelines
2 parents 6779d2a + 5d6a7e7 commit 3c89776

1 file changed

Lines changed: 332 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 332 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,332 @@
1+
# Contributing to PyNumDiff
2+
3+
Thank you for your interest in contributing to PyNumDiff! This document provides guidelines and instructions for contributing to the project.
4+
5+
## Table of Contents
6+
7+
- [How Can I Contribute?](#how-can-i-contribute)
8+
- [Development Setup](#development-setup)
9+
- [Code Style Guidelines](#code-style-guidelines)
10+
- [Testing Guidelines](#testing-guidelines)
11+
- [Pull Request Process](#pull-request-process)
12+
- [Reporting Bugs](#reporting-bugs)
13+
- [Proposing Features](#proposing-features)
14+
15+
## How Can I Contribute?
16+
17+
### Contributing Code
18+
19+
1. Look for issues labeled `good first issue` if you're new to the project
20+
2. Fork the repository
21+
3. Create a branch for your changes
22+
4. Make your changes following our guidelines
23+
5. Submit a pull request
24+
25+
## Development Setup
26+
27+
### Prerequisites
28+
29+
- Python 3.11 or higher
30+
- Git
31+
- (Optional) A virtual environment manager (venv, conda, etc.)
32+
33+
### Setting Up the Development Environment
34+
35+
1. **Fork the repository** on GitHub
36+
37+
2. **Clone your fork** locally:
38+
```bash
39+
git clone https://github.com/YOUR_USERNAME/PyNumDiff.git
40+
cd PyNumDiff
41+
```
42+
43+
3. **Add the upstream repository**:
44+
```bash
45+
git remote add upstream https://github.com/florisvb/PyNumDiff.git
46+
```
47+
48+
4. **Create a virtual environment** (recommended):
49+
```bash
50+
# Using venv
51+
python -m venv venv
52+
53+
# Activate on Windows
54+
venv\Scripts\activate
55+
56+
# Activate on macOS/Linux
57+
source venv/bin/activate
58+
```
59+
60+
5. **Install the package in development mode**:
61+
```bash
62+
pip install -e .
63+
```
64+
65+
6. **Install development dependencies**:
66+
```bash
67+
pip install pytest pylint
68+
```
69+
70+
7. **Verify the installation**:
71+
```bash
72+
pytest -s
73+
```
74+
75+
### Project Structure
76+
77+
- `pynumdiff/` - Main source code
78+
- `examples/` - Jupyter notebook examples
79+
- `docs/` - Documentation source files
80+
- `.github/workflows/` - GitHub Actions CI configuration
81+
- `tests/` - Test files (if applicable)
82+
83+
## Code Style Guidelines
84+
85+
### Python Style Guide
86+
87+
There's no strict coding style enforced. The main guideline is to match the existing code style in the project. When contributing:
88+
89+
- Match existing method signatures and docstring formats
90+
- Follow the naming conventions used in the existing codebase
91+
- Use 4 spaces for indentation (no tabs)
92+
93+
### Code Quality
94+
95+
The project uses `pylint` for code quality checks. While linting hasn't been strictly enforced recently, it will be important for the planned JOSS (Journal of Open Source Software) submission, which has stricter requirements.
96+
97+
To run linting checks:
98+
99+
1. **Run pylint** on your changes:
100+
```bash
101+
pylint pynumdiff/
102+
```
103+
104+
2. **Or use the project's linting script**:
105+
```bash
106+
python linting.py
107+
```
108+
109+
### Editor Configuration
110+
111+
The project includes an `.editorconfig` file that ensures consistent formatting. Most modern editors support EditorConfig automatically.
112+
113+
## Testing Guidelines
114+
115+
### Running Tests
116+
117+
PyNumDiff uses `pytest` for testing. To run tests:
118+
119+
```bash
120+
# Run all tests
121+
pytest -s
122+
123+
# Run tests with plots (to visualize method results)
124+
pytest -s --plot
125+
126+
# Run tests with bounds (to print log error bounds)
127+
pytest -s --bounds
128+
```
129+
130+
### Writing Tests
131+
132+
- Write tests for new features and bug fixes
133+
- Follow the existing test structure
134+
- Ensure all tests pass before submitting a PR
135+
- Tests should be deterministic and not depend on external resources
136+
137+
The test suite is organized into several test files:
138+
- `test_diff_methods`: Broadly tests for correctness and ability to actually differentiate
139+
- `test_utils`: Contains tests of miscellaneous functionality like simulations and evaluation metrics
140+
- `test_optimize`: Tests the hyperparameter optimization code
141+
142+
### Continuous Integration
143+
144+
The project uses GitHub Actions for continuous integration. All pull requests are automatically tested. Make sure your changes pass all CI checks before requesting a review.
145+
146+
## Pull Request Process
147+
148+
### Before Submitting
149+
150+
1. **Update your fork** with the latest changes from upstream:
151+
```bash
152+
git fetch upstream
153+
git checkout master
154+
git merge upstream/master
155+
```
156+
157+
2. **Create a feature branch**:
158+
```bash
159+
git checkout -b feature/your-feature-name
160+
# or
161+
git checkout -b fix/your-bug-fix-name
162+
```
163+
164+
3. **Make your changes** following the code style guidelines
165+
166+
4. **Write or update tests** as needed
167+
168+
5. **Run tests** to ensure everything passes:
169+
```bash
170+
pytest -s
171+
```
172+
173+
6. **Run linting** to check code quality:
174+
```bash
175+
python linting.py
176+
```
177+
178+
7. **Commit your changes** with clear, descriptive commit messages (see [Commit Messages](#commit-messages))
179+
180+
### Submitting a Pull Request
181+
182+
1. **Push your branch** to your fork:
183+
```bash
184+
git push origin feature/your-feature-name
185+
```
186+
187+
2. **Open a Pull Request** on GitHub:
188+
- Go to the [PyNumDiff repository](https://github.com/florisvb/PyNumDiff)
189+
- Click "New Pull Request"
190+
- Select your fork and branch
191+
- Fill out the PR template with:
192+
- A clear title and description
193+
- Reference to the related issue (e.g., "Fixes #169")
194+
- Description of changes
195+
- Any breaking changes
196+
197+
3. **Wait for CI** to run and ensure all checks pass
198+
199+
4. **Respond to feedback** from maintainers and reviewers
200+
201+
5. **Keep your PR up to date** by rebasing on master if needed:
202+
```bash
203+
git fetch upstream
204+
git rebase upstream/master
205+
git push --force-with-lease origin feature/your-feature-name
206+
```
207+
208+
### PR Guidelines
209+
210+
- Smaller, focused PRs are generally easier to review
211+
- Ensure all CI checks pass
212+
- Request review from maintainers when ready
213+
- Be responsive to feedback
214+
215+
## Reporting Bugs
216+
217+
### Before Submitting a Bug Report
218+
219+
1. **Check existing issues** to see if the bug has already been reported
220+
2. **Test with the latest version** to ensure the bug still exists
221+
3. **Check the documentation** to ensure you're using the library correctly
222+
223+
### How to Report a Bug
224+
225+
When reporting a bug, please include:
226+
227+
1. **Clear and descriptive title**
228+
2. **Steps to reproduce**:
229+
- What you were trying to do
230+
- What you expected to happen
231+
- What actually happened
232+
3. **Minimal code example** that reproduces the issue
233+
4. **Environment information**:
234+
- Python version
235+
- PyNumDiff version
236+
- Operating system
237+
5. **Error messages** or stack traces (if applicable)
238+
6. **Additional context** (screenshots, data files, etc.)
239+
240+
### Bug Report Template
241+
242+
```markdown
243+
**Describe the bug**
244+
A clear and concise description of what the bug is.
245+
246+
**To Reproduce**
247+
Steps to reproduce the behavior:
248+
1. ...
249+
2. ...
250+
251+
**Expected behavior**
252+
A clear and concise description of what you expected to happen.
253+
254+
**Code example**
255+
```python
256+
# Minimal code that reproduces the issue
257+
```
258+
259+
**Environment**
260+
- Python version:
261+
- PyNumDiff version:
262+
- OS:
263+
264+
**Additional context**
265+
Add any other context about the problem here.
266+
```
267+
268+
## Proposing Features
269+
270+
### Before Proposing a Feature
271+
272+
1. **Check existing issues** to see if the feature has been discussed
273+
2. **Consider the scope** - is it within the project's goals?
274+
3. **Think about implementation** - is it feasible?
275+
276+
### How to Propose a Feature
277+
278+
When proposing a feature, please include:
279+
280+
1. **Clear and descriptive title**
281+
2. **Problem statement**: What problem does this feature solve?
282+
3. **Proposed solution**: How would you implement it?
283+
4. **Alternatives considered**: What other approaches did you consider?
284+
5. **Additional context**: Examples, use cases, etc.
285+
286+
### Feature Request Template
287+
288+
```markdown
289+
**Is your feature request related to a problem?**
290+
A clear and concise description of what the problem is.
291+
292+
**Describe the solution you'd like**
293+
A clear and concise description of what you want to happen.
294+
295+
**Describe alternatives you've considered**
296+
A clear and concise description of any alternative solutions or features you've considered.
297+
298+
**Additional context**
299+
Add any other context or examples about the feature request here.
300+
```
301+
302+
## Commit Messages
303+
304+
We encourage descriptive commit messages that explain what changed and why.
305+
Long, detailed commit messages are appreciated as they help others understand
306+
the project's history.
307+
308+
### Types
309+
310+
- `feat`: A new feature
311+
- `fix`: A bug fix
312+
- `docs`: Documentation only changes
313+
- `style`: Code style changes (formatting, missing semicolons, etc.)
314+
- `refactor`: Code refactoring without changing functionality
315+
316+
## Questions?
317+
318+
If you have questions about contributing:
319+
320+
1. Check the [documentation](https://pynumdiff.readthedocs.io/)
321+
2. Look through [existing issues](https://github.com/florisvb/PyNumDiff/issues)
322+
3. Open a new issue with the `question` label
323+
324+
## Additional Resources
325+
326+
- [PyNumDiff Documentation](https://pynumdiff.readthedocs.io/)
327+
- [Project README](README.md)
328+
- [GitHub Issues](https://github.com/florisvb/PyNumDiff/issues)
329+
- [PEP 8 Style Guide](https://www.python.org/dev/peps/pep-0008/)
330+
- [pytest Documentation](https://docs.pytest.org/)
331+
332+
Thank you for contributing to PyNumDiff! 🎉

0 commit comments

Comments
 (0)