ab.dem.tf.changemaker/mkdocs/docs/contributing/collaboration.md

Collaboration Best Practices

Working effectively with others is key to successful project contribution. This guide covers how to collaborate smoothly, handle conflicts, and be a positive community member.

Being a Good Collaborator

Communicate Clearly

• Be specific in your questions and descriptions
• Use examples when explaining problems or suggestions
• Be patient - people have different schedules and time zones
• Ask for help when you're stuck - it's better than struggling alone

Respect Others' Work

• Read existing content before making changes to understand the current approach
• Build on others' contributions rather than completely replacing them
• Give credit when you're building on someone else's ideas
• Discuss major changes before implementing them

Stay Focused on the Mission

Remember we're all working toward the same goal: defending democracy in Alberta. Keep discussions:

• Constructive rather than critical
• Focused on the work rather than personal preferences
• Aligned with our values of democratic participation and transparency

Working with Issues

Finding Work to Do

1. Check the Issues tab for tasks marked "good first issue" or "help wanted"
2. Read through the description to understand what's needed
3. Comment on the issue to let others know you're working on it
4. Ask questions if anything is unclear

Reporting Problems

When you find a bug or have a suggestion:

1. Check existing issues first to avoid duplicates

2. Use a clear title like "Mobile menu doesn't work on iPhone"

3. Provide details:

   • What you expected to happen
   • What actually happened
   • Steps to reproduce the problem
   • What browser/device you're using

4. Add labels if you have permission (bug, enhancement, etc.)

Handling Disagreements

When You Disagree with Feedback

Sometimes you might disagree with a reviewer's suggestions:

Step 1: Understand their perspective

• Ask clarifying questions
• Consider that they might have context you don't
• Look at how similar issues were handled before

Step 2: Explain your reasoning

• Share why you made the choice you did
• Provide evidence or examples if relevant
• Be open to finding a compromise solution

Step 3: Involve others if needed

• If you can't reach agreement, ask other team members for input
• Tag project maintainers for guidance
• Remember the goal is the best outcome for the project

When Others Disagree with You

If someone challenges your review or suggestion:

• Stay calm and professional
• Re-examine your position - you might have missed something
• Focus on the project's needs rather than being "right"
• Be willing to change your mind when presented with good reasoning

Managing Merge Conflicts

Sometimes Git can't automatically combine changes - this creates a "merge conflict."

Why Conflicts Happen

• Two people edited the same lines in a file
• Someone deleted a file that another person modified
• Changes were made to the same section but in different ways

Resolving Simple Conflicts

1. Don't panic - conflicts are normal and fixable
2. Look at the conflicted sections - Git marks them clearly
3. Decide which version to keep or how to combine them
4. Remove the conflict markers (<<<<<<<, =======, >>>>>>>)
5. Test that everything still works
6. Commit the resolution

When to Ask for Help

• If you're not sure which version to keep
• If the conflict involves code you didn't write
• If there are many conflicts or they seem complex
• If you're new to Git and feeling overwhelmed

Communication Channels

Where to Discuss What

Pull Request Comments: For discussing specific changes in your submission

Issue Comments: For general discussion about problems or improvements

Project Chat/Forum: For real-time questions and community discussion

Email: For private matters or when you need direct help

Response Time Expectations

• Pull request reviews: Usually within 2-3 business days
• Issue responses: Within a week for non-urgent matters
• Chat messages: Best effort during business hours
• Emergency fixes: Tag maintainers for faster response

Building Community

Help Other Contributors

• Answer questions when you can help
• Review others' pull requests if you feel confident
• Share resources you've found helpful
• Welcome new contributors and help them get started

Stay Engaged

• Follow project updates to stay informed about changes
• Participate in discussions about the project's direction
• Attend community meetings if they're held
• Share the project with others who might want to contribute

Red Flags to Avoid

These behaviors can harm the collaborative environment:

• Personal attacks or hostile language
• Dismissing others' contributions without constructive feedback
• Making unilateral decisions about major changes
• Ignoring established processes without discussion
• Taking credit for others' work

Video Tutorial

[Administrator: Add a video tutorial showing examples of good collaboration, how to handle feedback constructively, and conflict resolution strategies]

Quick Do's and Don'ts

Do:

• ✅ Ask questions when unsure
• ✅ Give specific, helpful feedback
• ✅ Test your changes before submitting
• ✅ Respond to feedback promptly
• ✅ Help others when you can

Don't:

• ❌ Make personal attacks or hostile comments
• ❌ Ignore project conventions without discussion
• ❌ Submit untested changes
• ❌ Take feedback personally
• ❌ Work in isolation on major changes

Remember

Good collaboration makes everyone more effective and creates a positive environment where people want to contribute. By following these practices, you're not just improving the website - you're helping build a stronger community committed to defending democracy in Alberta.