MidasEngine/docs/PoliciesAndStandards/CommunicationStandards.md

Collaboration and Communication

Table of Contents

1. Purpose
2. Communication Channels
   • GitHub Issues
   • Pull Requests (PRs)
   • Team Meetings
   • Direct Messaging (DMs)
3. Collaborative Coding Practices
4. Documentation Requirements
5. Conflict Resolution
6. File-Path Standards and Naming Conventions
7. Labor Distribution and Task Assignment

---

Purpose

This document outlines collaboration and communication guidelines for our team, ensuring alignment, productivity, and clarity as we work on projects. Effective use of these practices will help streamline progress and minimize misunderstandings.

---

Communication Channels

1. GitHub Issues

   • Purpose: Use GitHub Issues for bug tracking, feature requests, and all development-related discussions.
   • Best Practices:
     • Assign labels (e.g., bug, enhancement, documentation) to categorize each issue.
     • Assign issues to relevant team members and add milestones where applicable.
     • Keep all discussions regarding the issue within its thread to retain context.

2. Pull Requests (PRs)

   • Purpose: PRs facilitate code reviews and collaborative discussions on changes before merging.
   • Best Practices:
     • Link each PR to the corresponding issue.
     • Use the provided PR Template to give detailed context and link to relevant resources.
     • Use GitHub Reviews to comment on specific code sections or suggest improvements.
     • Ensure all discussions are resolved before finalizing the merge.

3. Team Meetings

   • Purpose: Conduct periodic meetings to discuss project updates, roadblocks, and future priorities.
   • Frequency: Weekly, or as needed based on project milestones.
   • Agenda: Each member should come prepared with updates, questions, and any roadblocks requiring group input.

4. Direct Messaging (DMs)

   • Purpose: Use text messaging for quick, urgent issues.
   • Future Option: A company Discord or similar platform may be established for more structured and real-time communication, enabling different channels for topics like bugs, general updates, and discussions.
   • Note: Text messaging or direct messages are meant for time-sensitive issues and should not replace documented discussions crucial to the project.

---

Collaborative Coding Practices

1. Code Reviews

   • Open a PR for any code that is ready for review.
   • Assign relevant team members as reviewers, tagging specific people for feedback on particular areas.
   • Provide constructive feedback with explanations to clarify your suggestions.

2. Issue Assignment and Management

   • Assign each issue to one or more contributors.
   • Regularly update the issue status by changing labels or closing it when complete.
   • For large tasks, break down the issue into smaller, manageable sub-tasks and assign them accordingly.

3. Pair Programming and Knowledge Sharing

   • For complex features or debugging, consider pair programming with another team member.
   • Document insights gained from these sessions, especially any solutions for particularly challenging issues or bugs.

Task Ownership and Assignment Changes

To ensure transparency and accountability within the team, follow these guidelines for task ownership:

• Task Ownership: Each issue should have a clearly assigned owner responsible for its completion. If you are assigned a task, regularly update the issue with your progress.
• Reassignment Protocol: If you are unable to complete a task or require assistance, reassign it to a relevant team member or reach out to the project maintainer.
• Ownership Transfer: When transferring ownership, add a comment to the GitHub issue explaining the reason and notify the new owner directly. Ensure the transition is smooth to maintain workflow continuity.

Maintaining clear task ownership helps keep the project organized and reduces overlap or duplicated effort.

---

Documentation Requirements

• Each project module should contain a README.md with setup instructions, usage examples, and module-specific details.
• Follow Documentation Standards.md for consistency in all documentation.
• Comment complex or non-obvious code to enhance clarity for all team members.

---

Conflict Resolution

1. Technical Disagreements

   • Address technical disagreements within the PR or issue thread.
   • If unresolved, escalate to a team meeting where a consensus can be reached.

2. Responsibilities and Expectations

   • Document each team member’s responsibilities and ensure clarity on roles to prevent misunderstandings.
   • If conflicts arise regarding tasks, discuss openly in team meetings or escalate to the project maintainer.

---

File-Path Standards and Naming Conventions

• Adhere to the File-Path Standards for directory structures and file naming conventions.
• Following consistent naming conventions helps streamline navigation and allows the team to understand the project structure quickly.

---

Labor Distribution and Task Assignment

GitHub Project Boards and Issues provide a structured method for distributing tasks across the team:

1. Create Project Boards

   • Purpose: Use GitHub Project Boards to organize issues into columns such as To Do, In Progress, and Completed.
   • Best Practices:
     • Ensure each task or issue is visible on the board.
     • Regularly update the status of each issue by moving it to the relevant column as work progresses.

2. Assigning Issues and Tasks

   • For each feature or task, create an issue in GitHub and assign it to the responsible contributor.
   • Use tags like priority, in-progress, and review-needed for clarity on the status and urgency of each task.

3. Milestones

   • Define milestones for specific project phases (e.g., v1.0 Launch, Feature Complete).
   • Assign issues to milestones to maintain a timeline and prioritize critical tasks.
   • Each milestone should have an estimated completion date and a list of issues to be resolved before the milestone is considered complete.