Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at https://github.com/biglocalnews/civic-scraper/issues.

If you are reporting a bug, please include:

Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/biglocalnews/civic-scraper/issues.

If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions are welcome :)

Do Research

This project involves a fair bit of research, especially with respect to locating platforms and sites to scrape. Research jobs are great ways to get involved if you don’t write code but still want to pitch in. Anything tagged with the “research” and “help wanted” labels on GitHub is fair game.

Write Documentation

civic-scraper could always use more documentation, whether as part of the official civic-scraper docs, in docstrings, or even on the web in blog posts, articles, and such.

Our official docs use reStructuredText and Sphinx. To contribute documentation without completing the full repo setup (only required for code logic):

Fork and clone this repo
Install uv for Python project and package management
Install doc dependencies: uv sync --group docs
Create a branch for your doc updates and start writing!
- Use make serve-docs command to run a Sphinx server locally that displays doc pages and allows auto reloading of pages in browser when changes are made to a file.
Create a GitHub Pull Request once you’re ready to send us your changes

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it. Follow the Get Started instructions below to get your local environment setup.

Implement Features

Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it. Follow the Get Started instructions below to get your local environment setup.

Get Started!

Ready to contribute a bug fix or feature? Here’s how to set up civic-scraper for local development.

Fork and clone the `civic-scraper` repo

Fork the civic-scraper repo on GitHub.

Clone your fork locally:

$ git clone git@github.com:your_name_here/civic-scraper.git

Prep your development environment

Install uv for Python project and package management

curl -LsSf https://astral.sh/uv/install.sh | sh

Create your virtual environment & install dependencies

In the root of the project directory, run
```
uv sync
```
This creates a virtual environment and installs all dependencies.
Install the pre-commit hooks:
```
uv run pre-commit install
```
This ensures your code is automatically checked for formatting and linting issues before each commit.

Making changes

Create a branch for local development on your fork:

$ git checkout -b name-of-your-bugfix-or-feature

Make your changes and be sure to add/update tests!

Check your changes

When you’re done making changes, you’ll want to check that your changes pass linting and formatting requirements and the tests, including testing other Python versions.

Run all pre-commit checks:
```
uv run pre-commit run --all-files
```
This runs black (formatting), isort (import sorting), flake8 (linting), and other checks.
Run tests:
```
make test
```
To run tests across all supported Python versions (3.9, 3.10, 3.11):
```
make test-all
```

Commit your changes and push your branch to GitHub:

$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

The pull request should include tests.
If the pull request adds functionality, please be sure to review the docs and include necessary updates. For example, new classes, methods and functions should be documented.
The pull request should work for Python version 3.9 or higher. Check the GitHub Actions workflow on your pull request to make sure that the tests pass for all supported Python versions.