158 lines
4.8 KiB
Markdown
158 lines
4.8 KiB
Markdown
# 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!
|