Skip to content

Commit b03bdaf

Browse files
Nimra-FayazNimra-Fayaz
committed
docs: add CONTRIBUTING.md with comprehensive guidelines
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 #169 and provides clear guidance for new contributors to get started with the project. Fixes #169
1 parent bea8abb commit b03bdaf

File tree

1 file changed

+393
-0
lines changed

1 file changed

+393
-0
lines changed

‎CONTRIBUTING.md‎

Lines changed: 393 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,393 @@
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. Following these guidelines helps communicate that you respect the time of the developers managing and developing this open-source project.
4+
5+
## Table of Contents
6+
7+
- [Code of Conduct](#code-of-conduct)
8+
- [How Can I Contribute?](#how-can-i-contribute)
9+
- [Development Setup](#development-setup)
10+
- [Code Style Guidelines](#code-style-guidelines)
11+
- [Testing Guidelines](#testing-guidelines)
12+
- [Pull Request Process](#pull-request-process)
13+
- [Reporting Bugs](#reporting-bugs)
14+
- [Proposing Features](#proposing-features)
15+
- [Commit Message Conventions](#commit-message-conventions)
16+
- [Questions?](#questions)
17+
18+
## Code of Conduct
19+
20+
This project adheres to a code of conduct that all contributors are expected to follow. Please be respectful and constructive in all interactions.
21+
22+
## How Can I Contribute?
23+
24+
### Reporting Bugs
25+
26+
If you find a bug, please report it by [opening an issue](https://github.com/florisvb/PyNumDiff/issues/new). See the [Reporting Bugs](#reporting-bugs) section for details.
27+
28+
### Suggesting Enhancements
29+
30+
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.
31+
32+
### Contributing Code
33+
34+
1. Look for issues labeled `good first issue` if you're new to the project
35+
2. Fork the repository
36+
3. Create a branch for your changes
37+
4. Make your changes following our guidelines
38+
5. Submit a pull request
39+
40+
## Development Setup
41+
42+
### Prerequisites
43+
44+
- Python 3.7 or higher
45+
- Git
46+
- (Optional) A virtual environment manager (venv, conda, etc.)
47+
48+
### Setting Up the Development Environment
49+
50+
1. **Fork the repository** on GitHub
51+
52+
2. **Clone your fork** locally:
53+
```bash
54+
git clone https://github.com/YOUR_USERNAME/PyNumDiff.git
55+
cd PyNumDiff
56+
```
57+
58+
3. **Add the upstream repository**:
59+
```bash
60+
git remote add upstream https://github.com/florisvb/PyNumDiff.git
61+
```
62+
63+
4. **Create a virtual environment** (recommended):
64+
```bash
65+
# Using venv
66+
python -m venv venv
67+
68+
# Activate on Windows
69+
venv\Scripts\activate
70+
71+
# Activate on macOS/Linux
72+
source venv/bin/activate
73+
```
74+
75+
5. **Install the package in development mode**:
76+
```bash
77+
pip install -e .
78+
```
79+
80+
6. **Install development dependencies**:
81+
```bash
82+
pip install pytest pylint
83+
```
84+
85+
7. **Verify the installation**:
86+
```bash
87+
pytest -s
88+
```
89+
90+
### Project Structure
91+
92+
- `pynumdiff/` - Main source code
93+
- `examples/` - Jupyter notebook examples
94+
- `docs/` - Documentation source files
95+
- `.github/workflows/` - GitHub Actions CI configuration
96+
- `tests/` - Test files (if applicable)
97+
98+
## Code Style Guidelines
99+
100+
### Python Style Guide
101+
102+
PyNumDiff follows [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guidelines. Here are the key points:
103+
104+
- Use 4 spaces for indentation (no tabs)
105+
- Maximum line length: 79 characters (soft limit) or 99 characters (hard limit)
106+
- Use meaningful variable and function names
107+
- Follow naming conventions:
108+
- Functions and variables: `snake_case`
109+
- Classes: `PascalCase`
110+
- Constants: `UPPER_SNAKE_CASE`
111+
112+
### Code Quality
113+
114+
The project uses `pylint` for code quality checks. Before submitting a PR:
115+
116+
1. **Run pylint** on your changes:
117+
```bash
118+
pylint pynumdiff/
119+
```
120+
121+
2. **Or use the project's linting script**:
122+
```bash
123+
python linting.py
124+
```
125+
126+
3. **Fix any issues** reported by pylint before submitting your PR
127+
128+
### Editor Configuration
129+
130+
The project includes an `.editorconfig` file that ensures consistent formatting. Most modern editors support EditorConfig automatically.
131+
132+
## Testing Guidelines
133+
134+
### Running Tests
135+
136+
PyNumDiff uses `pytest` for testing. To run tests:
137+
138+
```bash
139+
# Run all tests
140+
pytest -s
141+
142+
# Run tests with plots (to visualize method results)
143+
pytest -s --plot
144+
145+
# Run tests with bounds (to print log error bounds)
146+
pytest -s --bounds
147+
```
148+
149+
### Writing Tests
150+
151+
- Write tests for new features and bug fixes
152+
- Follow the existing test structure
153+
- Ensure all tests pass before submitting a PR
154+
- Tests should be deterministic and not depend on external resources
155+
156+
### Continuous Integration
157+
158+
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.
159+
160+
## Pull Request Process
161+
162+
### Before Submitting
163+
164+
1. **Update your fork** with the latest changes from upstream:
165+
```bash
166+
git fetch upstream
167+
git checkout master
168+
git merge upstream/master
169+
```
170+
171+
2. **Create a feature branch**:
172+
```bash
173+
git checkout -b feature/your-feature-name
174+
# or
175+
git checkout -b fix/your-bug-fix-name
176+
```
177+
178+
3. **Make your changes** following the code style guidelines
179+
180+
4. **Write or update tests** as needed
181+
182+
5. **Run tests** to ensure everything passes:
183+
```bash
184+
pytest -s
185+
```
186+
187+
6. **Run linting** to check code quality:
188+
```bash
189+
python linting.py
190+
```
191+
192+
7. **Commit your changes** with clear, descriptive commit messages (see [Commit Message Conventions](#commit-message-conventions))
193+
194+
### Submitting a Pull Request
195+
196+
1. **Push your branch** to your fork:
197+
```bash
198+
git push origin feature/your-feature-name
199+
```
200+
201+
2. **Open a Pull Request** on GitHub:
202+
- Go to the [PyNumDiff repository](https://github.com/florisvb/PyNumDiff)
203+
- Click "New Pull Request"
204+
- Select your fork and branch
205+
- Fill out the PR template with:
206+
- A clear title and description
207+
- Reference to the related issue (e.g., "Fixes #169")
208+
- Description of changes
209+
- Any breaking changes
210+
211+
3. **Wait for CI** to run and ensure all checks pass
212+
213+
4. **Respond to feedback** from maintainers and reviewers
214+
215+
5. **Keep your PR up to date** by rebasing on master if needed:
216+
```bash
217+
git fetch upstream
218+
git rebase upstream/master
219+
git push --force-with-lease origin feature/your-feature-name
220+
```
221+
222+
### PR Guidelines
223+
224+
- Keep PRs focused on a single issue or feature
225+
- Keep PRs reasonably sized (if large, consider breaking into smaller PRs)
226+
- Ensure all CI checks pass
227+
- Request review from maintainers when ready
228+
- Be responsive to feedback
229+
230+
## Reporting Bugs
231+
232+
### Before Submitting a Bug Report
233+
234+
1. **Check existing issues** to see if the bug has already been reported
235+
2. **Test with the latest version** to ensure the bug still exists
236+
3. **Check the documentation** to ensure you're using the library correctly
237+
238+
### How to Report a Bug
239+
240+
When reporting a bug, please include:
241+
242+
1. **Clear and descriptive title**
243+
2. **Steps to reproduce**:
244+
- What you were trying to do
245+
- What you expected to happen
246+
- What actually happened
247+
3. **Minimal code example** that reproduces the issue
248+
4. **Environment information**:
249+
- Python version
250+
- PyNumDiff version
251+
- Operating system
252+
5. **Error messages** or stack traces (if applicable)
253+
6. **Additional context** (screenshots, data files, etc.)
254+
255+
### Bug Report Template
256+
257+
```markdown
258+
**Describe the bug**
259+
A clear and concise description of what the bug is.
260+
261+
**To Reproduce**
262+
Steps to reproduce the behavior:
263+
1. ...
264+
2. ...
265+
266+
**Expected behavior**
267+
A clear and concise description of what you expected to happen.
268+
269+
**Code example**
270+
```python
271+
# Minimal code that reproduces the issue
272+
```
273+
274+
**Environment**
275+
- Python version:
276+
- PyNumDiff version:
277+
- OS:
278+
279+
**Additional context**
280+
Add any other context about the problem here.
281+
```
282+
283+
## Proposing Features
284+
285+
### Before Proposing a Feature
286+
287+
1. **Check existing issues** to see if the feature has been discussed
288+
2. **Consider the scope** - is it within the project's goals?
289+
3. **Think about implementation** - is it feasible?
290+
291+
### How to Propose a Feature
292+
293+
When proposing a feature, please include:
294+
295+
1. **Clear and descriptive title**
296+
2. **Problem statement**: What problem does this feature solve?
297+
3. **Proposed solution**: How would you implement it?
298+
4. **Alternatives considered**: What other approaches did you consider?
299+
5. **Additional context**: Examples, use cases, etc.
300+
301+
### Feature Request Template
302+
303+
```markdown
304+
**Is your feature request related to a problem?**
305+
A clear and concise description of what the problem is.
306+
307+
**Describe the solution you'd like**
308+
A clear and concise description of what you want to happen.
309+
310+
**Describe alternatives you've considered**
311+
A clear and concise description of any alternative solutions or features you've considered.
312+
313+
**Additional context**
314+
Add any other context or examples about the feature request here.
315+
```
316+
317+
## Commit Message Conventions
318+
319+
### Commit Message Format
320+
321+
We follow a conventional commit message format:
322+
323+
```
324+
<type>(<scope>): <subject>
325+
326+
<body>
327+
328+
<footer>
329+
```
330+
331+
### Types
332+
333+
- `feat`: A new feature
334+
- `fix`: A bug fix
335+
- `docs`: Documentation only changes
336+
- `style`: Code style changes (formatting, missing semicolons, etc.)
337+
- `refactor`: Code refactoring without changing functionality
338+
- `test`: Adding or updating tests
339+
- `chore`: Maintenance tasks (dependencies, build config, etc.)
340+
341+
### Examples
342+
343+
```
344+
feat(optimize): add support for custom search spaces
345+
346+
Allow users to specify custom parameter search spaces in the
347+
optimize function for better control over hyperparameter tuning.
348+
349+
Fixes #123
350+
```
351+
352+
```
353+
fix(differentiation): correct boundary condition handling
354+
355+
Fixed an issue where boundary conditions were not properly
356+
handled for signals with variable step sizes.
357+
358+
Closes #456
359+
```
360+
361+
```
362+
docs(readme): update installation instructions
363+
364+
Updated README with clearer installation steps for Windows users.
365+
```
366+
367+
### Guidelines
368+
369+
- Use the imperative mood ("add feature" not "added feature")
370+
- Keep the subject line under 50 characters
371+
- Capitalize the subject line
372+
- Do not end the subject line with a period
373+
- Use the body to explain what and why vs. how
374+
- Reference issues and PRs in the footer
375+
376+
## Questions?
377+
378+
If you have questions about contributing:
379+
380+
1. Check the [documentation](https://pynumdiff.readthedocs.io/)
381+
2. Look through [existing issues](https://github.com/florisvb/PyNumDiff/issues)
382+
3. Open a new issue with the `question` label
383+
384+
## Additional Resources
385+
386+
- [PyNumDiff Documentation](https://pynumdiff.readthedocs.io/)
387+
- [Project README](README.md)
388+
- [GitHub Issues](https://github.com/florisvb/PyNumDiff/issues)
389+
- [PEP 8 Style Guide](https://www.python.org/dev/peps/pep-0008/)
390+
- [pytest Documentation](https://docs.pytest.org/)
391+
392+
Thank you for contributing to PyNumDiff! 🎉
393+

0 commit comments

Comments
 (0)