Contributing to OneCite

Thank you for your interest in contributing to OneCite! This guide will help you get started.

Getting Started

1. Fork the Repository

Click the “Fork” button on the GitHub repository page.

2. Clone Your Fork

git clone https://github.com/your-username/OneCite.git
cd OneCite

3. Create a Branch

git checkout -b feature/your-feature-name
# or for bug fixes
git checkout -b fix/issue-description

4. Set Up Development Environment

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

Development Workflow

Code Style

We follow PEP 8 style guidelines. Use black for formatting:

black onecite/ tests/

Linting

Use flake8 to check code quality:

flake8 onecite/ tests/

Running Tests

Run the test suite:

pytest tests/

Check coverage:

pytest --cov=onecite tests/

Creating Commits

Write clear, descriptive commit messages:

# Good
git commit -m "Add support for custom templates"

# Bad
git commit -m "Fix stuff"

Use the imperative mood: “Add feature” not “Added feature”

Types of Contributions

Bug Reports

Before submitting a bug report:

Check existing issues to avoid duplicates
Include your Python and OneCite version
Provide a minimal code example to reproduce
Describe expected vs actual behavior

Template:

**Describe the bug**
[Description of the bug]

**To Reproduce**
[Steps to reproduce]

**Expected behavior**
[What should happen]

**Actual behavior**
[What actually happens]

**Environment**
- Python version: 3.x.x
- OneCite version: 0.x.x
- OS: Windows/macOS/Linux

Feature Requests

Describe:

What problem it solves
How it would be used
Any alternative approaches

Template:

**Is your feature request related to a problem?**
[Describe the problem]

**Describe the solution**
[Describe the proposed solution]

**Describe alternatives considered**
[Alternative solutions or features]

Code Contributions

1. Small Fixes

For typos, documentation, or small bugs:

Create a branch
Make the change
Test thoroughly
Submit a PR with clear description

2. New Features

For larger features:

Open an issue first to discuss
Wait for feedback from maintainers
Once approved, implement
Include tests and documentation
Submit PR

3. Bug Fixes

For bug fixes:

Open an issue describing the bug
Create a branch from the issue
Include a test that demonstrates the bug
Implement the fix
Ensure the test now passes

Documentation Improvements

Documentation is crucial! Contributions include:

Fixing typos
Clarifying explanations
Adding examples
Improving API documentation
Translating documentation

Submit documentation changes as PRs to the repository.

Submitting a Pull Request

Push to Your Fork

git push origin feature/your-feature-name

Create a Pull Request

Go to GitHub and click “New Pull Request”

PR Description

Include:

What change does it make?
Why is this change needed?
How has it been tested?
Any breaking changes?

Template:

## Description
[Brief description of changes]

## Related Issues
Closes #123

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation
- [ ] Other

## Testing
[Describe testing performed]

## Checklist
- [ ] Tests pass
- [ ] Code follows style guidelines
- [ ] Documentation updated
- [ ] No breaking changes

Code Review

A maintainer will review your PR. Be prepared to:

Discuss implementation
Address feedback
Make requested changes
Ensure tests pass

Merge

Once approved, a maintainer will merge your PR.

Testing Guidelines

Writing Tests

Tests should be:

Isolated - Not dependent on other tests
Clear - Easy to understand intent
Focused - Test one thing
Fast - Complete quickly

Example:

def test_process_references_with_doi():
    result = process_references(
        input_content="10.1038/nature14539",
        input_type="txt"
    )
    assert result['processed_count'] == 1
    assert '10.1038/nature14539' in result['output_content']

Running Tests

# Run all tests
pytest

# Run specific test file
pytest tests/test_cli.py

# Run specific test
pytest tests/test_cli.py::test_process_command

# Run with coverage
pytest --cov=onecite

Documentation Guidelines

Code Comments

Add docstrings to all functions and classes
Use Google-style docstrings

def process_references(input_content, input_type="txt"):
    """Process references and return formatted bibliography.

    Args:
        input_content (str): The reference content to process
        input_type (str): Type of input - "txt" or "bib"

    Returns:
        dict: Dictionary with output_content, processed_count, etc.

    Raises:
        ValidationError: If input is invalid
        ParseError: If parsing fails
    """

API Documentation

Update docstrings when changing:

Function signatures
Parameters
Return values
Exceptions
Behavior

Release Process

Versioning

OneCite follows Semantic Versioning:

MAJOR.MINOR.PATCH (e.g., 1.2.3)
MAJOR: Breaking changes
MINOR: New features (backward compatible)
PATCH: Bug fixes

Community Standards

Code of Conduct

Be respectful
Be inclusive
Provide constructive feedback
Accept criticism gracefully
Report inappropriate behavior

Communication

Use clear, professional language
Be patient with new contributors
Assume good intentions
Help educate when needed

Project Leadership

The OneCite Team:

Makes final decisions on features and releases
Reviews and merges PRs
Maintains project standards
Responds to issues and discussions

Getting Help

Check existing documentation
Search closed issues and PRs
Ask in GitHub Discussions
Contact maintainers if needed

Additional Resources

Recognition

Contributors are recognized in:

Release notes
README acknowledgments
GitHub contributors page

Thank you for making OneCite better!

Next Steps

Check the issues page for good first issues
Read existing code and tests
Start with documentation or small fixes
Ask questions in discussions