ab.dem.tf.changemaker/mkdocs/docs/contributing/submitting-changes.md

Submitting Changes

Whether you're editing through the web interface or working locally, this guide covers best practices for submitting your changes and navigating the review process.

Before You Submit

Step 1: Review Your Own Work

• Read through your changes as if seeing them for the first time
• Check for typos and grammar mistakes
• Verify links work and images display properly
• Make sure formatting looks correct in preview mode

Step 2: Write a Good Commit Message

Your commit message should clearly explain what you changed and why:

Good examples:

• "Fix broken link to voting rights resource"
• "Add FAQ section about Bill 54 implications"
• "Update contact information for Calgary office"

Poor examples:

• "Updated file"
• "Changes"
• "Fix"

Step 3: Check the Size of Your Changes

• Small focused changes are easier to review and more likely to be accepted quickly
• Large changes should be broken into smaller, logical pieces when possible
• If you must make large changes, explain why in your pull request description

Creating a Great Pull Request

Step 1: Choose a Clear Title

Your pull request title should summarize the main improvement:

• "Improve accessibility of navigation menu"
• "Add resources for municipal election information"
• "Fix mobile layout issues on FAQ page"

Step 2: Write a Helpful Description

Explain what you changed and why:

## What this changes

- Fixes the broken link to the Alberta Elections website
- Updates the FAQ to include information about the new voting procedures
- Adds alt text to images for screen readers

## Why this change is needed
The old link was returning a 404 error, and users were getting confused about the new voting procedures introduced in Bill 54.

## How to test

1. Click on the "Alberta Elections" link in the resources section
2. Verify it opens the correct page
3. Check that the FAQ section answers common questions about voting procedures

Step 3: Reference Related Issues

If your pull request fixes a reported issue:

• Include "Fixes #123" in the description (where 123 is the issue number)
• This automatically links your pull request to the issue

The Review Process

What Happens Next

1. Automated checks run to make sure your changes don't break anything
2. A team member reviews your changes within a few days
3. Discussion happens if they have questions or suggestions
4. Changes are approved and merged, or you're asked to make improvements

Responding to Feedback

When reviewers leave comments:

Be open to suggestions:

• Reviewers want to help improve the project
• They might know things about the project you don't
• Constructive feedback makes everyone better

Ask questions if unclear:

• "Could you give me an example of how you'd like this worded?"
• "I'm not sure I understand - could you clarify what you mean?"

Make requested changes promptly:

• Address feedback quickly to keep momentum
• Make additional commits to the same branch
• Your pull request will update automatically

Types of Feedback You Might Receive

Content suggestions:

• "Could you add a link to the source document here?"
• "This might be clearer if we break it into bullet points"

Technical improvements:

• "Please add alt text to this image for accessibility"
• "This link should open in a new tab"

Style consistency:

• "We use 'Alberta' instead of 'AB' throughout the site"
• "Can you match the heading format used on other pages?"

After Your Changes Are Merged

Celebrate!

You've successfully contributed to defending democracy in Alberta! Your changes are now live and helping others.

What's Next?

• Look for more ways to help - check the Issues tab for other needed improvements
• Share your knowledge - help other new contributors
• Stay engaged - watch for updates and continue contributing

Common Submission Mistakes

Avoid these pitfalls:

• Submitting changes without testing them first
• Making unrelated changes in the same pull request
• Not explaining why the change is needed
• Taking feedback personally instead of constructively

Quick Checklist

Before submitting any change:

• I've reviewed my own work for errors
• My commit message clearly describes the change
• My pull request has a clear title and description
• I've tested that my changes work as expected
• I've kept the change focused on one improvement

Video Tutorial

[Administrator: Add a video tutorial showing the pull request process, including how to respond to feedback and make revisions]

Getting Help

If you're unsure about any part of the submission process:

• Ask questions in your pull request
• Contact the project maintainers
• Join our contributor chat for real-time help

Remember: everyone was a beginner once, and the community is here to help you succeed!