Development

Contributing

How to contribute to ZineCore2 development

Thank you for your interest in contributing to ZineCore2! This guide explains how to contribute code, documentation, bug reports, and feature requests.

Ways to Contribute

Bug reports — Found a bug? Report it!
Feature requests — Ideas for improvements
Code contributions — Bug fixes and new features
Documentation — Improve guides and references
Testing — Help test new releases
Community support — Answer questions, help users

Before You Start

1. Check Existing Issues

Search GitHub Issues to avoid duplicates.

2. Understand the Project

Read the Architecture documentation
Review the ZineCore2 specification
Understand the four profiles

3. Join the Community

GitHub Discussions for questions
Community chat for real-time help

Reporting Bugs

Before Reporting

Check if it's already reported:

Search GitHub Issues
Check closed issues (might be fixed in unreleased version)

Verify it's a bug:

Can you reproduce it consistently?
Does it happen on a fresh install?
Is it documented behavior?

How to Report

Create a new issue with:

1. Clear title:

Bad: "It doesn't work"
Good: "API returns 500 error when creating zine with empty creator array"

2. Environment information:

- OS: Ubuntu 22.04
- Python version: 3.12.1
- Django version: 6.0.2
- ZineCore2 version: 1.2.0
- PostgreSQL version: 16.1

3. Steps to reproduce:

1. Create zine with empty creator array: POST /api/zines/ with {"creator": []}
2. Server returns 500 error
3. Error appears in logs

4. Expected behavior:

Should return 400 Bad Request with validation error

5. Actual behavior:

Returns 500 Internal Server Error

6. Error messages:

Traceback (most recent call last):
  File "...", line X, in ...
    ...
Exception: ...

7. Additional context:

Screenshots
API request/response bodies
Log files

Bug Report Template

## Environment
- OS:
- Python:
- Django:
- ZineCore2:

## Steps to Reproduce
1.
2.
3.

## Expected Behavior


## Actual Behavior


## Error Messages

Paste error messages here


## Additional Context

Requesting Features

Before Requesting

Check if it exists:

Search issues for similar requests
Check the specification (might already be defined)
Review the roadmap

Consider scope:

Is this a local customization? (Use custom fields)
Is this a spec change? (Discuss on spec repository)
Is this implementation-specific? (Good for this repo)

How to Request

Create an issue with:

1. Clear title:

Add bulk delete endpoint for zines

2. Use case:

As a cataloger managing large collections, I need to delete multiple
zines at once when records are duplicates or no longer needed.

3. Proposed solution:

Add DELETE /api/zines/bulk/ endpoint accepting array of zine IDs:

POST /api/zines/bulk-delete/
{
  "zine_ids": ["zine_001", "zine_002", "zine_003"]
}

Returns:
{
  "deleted": 3,
  "errors": []
}

4. Alternatives considered:

- Delete one at a time (too slow for large batches)
- Direct SQL (bypasses API validation)

5. Additional context:

Common workflow in library systems with duplicate detection.

Contributing Code

Setup Development Environment

# Fork repository on GitHub
# Clone your fork
git clone https://github.com/YOUR_USERNAME/server.git
cd server

# Add upstream remote
git remote add upstream https://github.com/ZineCore2/server.git

# Initialize submodules
git submodule update --init

# Setup virtual environment
uv venv
source .venv/bin/activate
uv sync

# Create database
createdb zinecore2

# Run migrations
cd backend
DJANGO_SETTINGS_MODULE=zinecore.settings.development \
  ../.venv/bin/python manage.py migrate

# Load vocabularies
DJANGO_SETTINGS_MODULE=zinecore.settings.development \
  ../.venv/bin/python manage.py load_vocabularies

# Run tests (should all pass)
DJANGO_SETTINGS_MODULE=zinecore.settings.development \
  ../.venv/bin/python manage.py test

Development Workflow

1. Create feature branch:

git checkout -b feature/descriptive-name

2. Make changes:

Follow Code Style
Write tests for new functionality
Update documentation if needed

3. Test your changes:

# Run all tests
DJANGO_SETTINGS_MODULE=zinecore.settings.development \
  python manage.py test

# Run specific test
DJANGO_SETTINGS_MODULE=zinecore.settings.development \
  python manage.py test catalog.tests.TestZineAPI

# Check code style (if configured)
black --check .
flake8 .

4. Commit changes:

git add .
git commit -m "Add bulk delete endpoint for zines

- Add DELETE /api/zines/bulk-delete/ endpoint
- Add tests for bulk deletion
- Update API documentation"

5. Push to your fork:

git push origin feature/descriptive-name

6. Create Pull Request:

Go to GitHub
Click "New Pull Request"
Select your branch
Fill out PR template

Pull Request Guidelines

Title:

Bad: "Fixed stuff"
Good: "Fix 500 error when creating zine with empty creator array"

Description should include:

## What This PR Does

Fixes #123

Adds validation to prevent 500 error when creator array is empty.
Now returns 400 Bad Request with clear error message.

## Changes Made

- Add validation in ZineWriteSerializer
- Add test case for empty creator array
- Update error message to be more descriptive

## Testing

- Added test: test_create_zine_empty_creator_array
- All existing tests pass
- Manually tested via API

## Screenshots (if applicable)

## Checklist

- [x] Tests added/updated
- [x] Documentation updated
- [x] All tests pass
- [x] Follows code style guidelines

Checklist:

Tests added for new functionality
All tests pass
Documentation updated
Follows code style guide
No unrelated changes
Commit messages are clear

Code Review Process

What to Expect

Initial review — Within 1-2 weeks
Feedback — Reviewers may request changes
Discussion — Be open to suggestions
Approval — When ready, PR will be approved
Merge — Maintainer merges to main

Responding to Feedback

DO:

✅ Respond to all comments
✅ Ask questions if unclear
✅ Make requested changes
✅ Mark resolved comments
✅ Be patient and respectful

DON'T:

❌ Take feedback personally
❌ Argue without technical justification
❌ Force-push after review (use new commits)
❌ Add unrelated changes

Common Review Feedback

"Please add tests"

# Add test for your feature
class TestBulkDelete(TestCase):
    def test_bulk_delete_zines(self):
        # Create test zines
        # Call bulk delete
        # Assert deleted
        pass

"Please update documentation"

Add to relevant documentation file or API docstring.

"Please follow code style"

Run code formatter:

black .

"Please make commits more focused"

Squash commits:

git rebase -i main
# Mark commits as 'squash' or 'fixup'

Contributing Documentation

Types of Documentation

1. Code documentation — Docstrings, comments 2. API documentation — This website 3. README — Quick start guide 4. CHANGELOG — Release notes

Documentation Guidelines

Use clear language:

Bad: "Utilize the serializer to transform the data"
Good: "Use the serializer to convert the data"

Include examples:

## Creating a Zine

```bash
curl -X POST http://localhost:8000/api/zines/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -d '{"zine_id": "zine_001", ...}'
```

Keep it up to date:

If code changes, update documentation in the same PR.

Where to Contribute Docs

Website documentation:

website/content/docs/ — Main documentation
Follow existing structure
Use markdown format

Code docstrings:

def create_zine(data):
    """
    Create a new zine record.

    Args:
        data (dict): Zine data including title, creator, etc.

    Returns:
        Zine: Created zine instance

    Raises:
        ValidationError: If data is invalid
    """
    pass