Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
69 lines (47 loc) · 4.94 KB

CONTRIBUTING.md

File metadata and controls

69 lines (47 loc) · 4.94 KB

Contributing to CivicTechWR Projects

We are excited to welcome contributors of every experience level who want to build civic technology for Waterloo Region. This guide covers how to plug into the community, find meaningful work, and collaborate effectively.

Community & Meetings

  • Weekly meetup: Wednesdays from 6:00–8:00 p.m. Eastern. Check the CivicTechWR Events for the latest location, session topics, and hybrid details.
  • Slack workspace: Join the conversation in Slack. Introduce yourself in #introductions and connect with project teams in their channels.
  • Project board: Browse active initiatives and open roles via the CivicTechWR Projects board.

Before You Start

  1. Review the Code of Conduct: Participation requires following the CivicTechWR Code of Conduct.
  2. Learn about the organization: The organization README outlines how default files apply across CivicTechWR repositories.
  3. Find a good first task: Explore open issues in the current repository, especially those labeled good first issue, help wanted, or documentation.
  4. Claim the work: Comment on the issue to let others know you are investigating. Maintainers will confirm and offer context.

Contribution Workflow

  1. Discuss the problem: Align on scope, acceptance criteria, and any blockers in Slack or the issue thread.
  2. Create a branch: Use a descriptive branch name such as feature/add-bus-routes or fix/accessibility-audit.
  3. Work iteratively: Commit early and often. Keep changes focused so they are easy to review.
  4. Run quality checks: Execute linting, tests, and accessibility checks that apply to the repository before pushing.
  5. Open a pull request: Complete the prompts in the pull request template, reference related issues, and request reviewers.

Development Guidelines

General Principles

  • Accessibility first: Align with WCAG 2.1 standards wherever possible.
  • Privacy by design: Collect and retain only the data a feature requires.
  • Community impact: Prioritize features that help Waterloo Region residents.
  • Maintainability: Write code and documentation future volunteers can understand.

Language- and Tool-Specific Tips

  • JavaScript/TypeScript: Follow the repository's lint configuration, format with Prettier when available, and add JSDoc or TSDoc comments for public APIs.
  • Python: Adhere to PEP 8, add docstrings, and prefer type hints for new modules.
  • CSS and design: Use semantic markup, responsive layouts, and contrast-checked color palettes. Test components with assistive technologies whenever feasible.
  • Documentation: Default to plain language, keep examples current, and update onboarding docs when workflows change.

Testing Expectations

  • Automated tests: Run the commands listed in the repository README (for example, npm test, pytest, or language-specific linters).
  • Accessibility checks: Use tools such as WAVE, axe DevTools, or browser accessibility inspectors.
  • Manual validation: Confirm key user journeys succeed on desktop and mobile devices. Document any known limitations in the pull request.

Communication Channels

  • Slack: Coordinate in Slack; project channels are the fastest way to get help.
  • GitHub issues: Use issues for tracking work, design discussions, and decisions so knowledge stays discoverable.
  • Email: Sensitive or non-public matters can be sent to civictechwr@gmail.com.
  • GitHub organizers team: Mention @CivicTechWR/organizers when a decision or review needs organizer attention.

This is a volunteer-driven community. Maintainers aim to respond to new issues within a week and review pull requests within two weeks, but availability varies. Flag time-sensitive work early so the team can coordinate support.

Recognition & Support

  • Contributors are highlighted during demo nights and in community updates.
  • Organizers can provide reference letters that describe your CivicTechWR impact.
  • We encourage pairing and co-working sessions—ask in Slack if you would like a buddy to collaborate with.

Questions or Ideas?

  • Post in the project channel on Slack.
  • Open a GitHub discussion or issue to capture proposals and feedback.
  • Connect with organizers at the next Wednesday meetup for real-time support.

Thank you for contributing your skills to CivicTechWR! Together we build technology that helps Waterloo Region thrive.