Collaboration Conventions

[Adamx090]

Hello guys! I apologize this came late. This is initial draft of the convention that we spoke of. A couple of points are already covered in the Contributing Guidelines document. Go over it and see if you are okay with it or we need to add or remove some points. If you all agree with it, I can start by fixing some of our previous work, like renaming things or creating issues retrospectively and such. Commit messages and merged branches names cannot be changed, because it's part of the PR immutable data. There appear to be a lot of information, but it actually not that much. Let me know your thoughts.

🧭 Collaboration Conventions

Conventions are essential for effective remote collaboration. They allow smooth, structured communication without the need for constant clarification or meetings. When followed consistently, they enable team members—and even third parties—to easily understand the project’s progress and decisions. This is especially helpful during project reviews or future revisits.

---

🔁 Workflow Conventions

🔹 Issues

• Always create an issue when planning to make changes in the repository.
• Every issue that introduces changes to the repository must be linked to a related Pull Request (PR).
• For minor fixes related to a previous issue, you can reopen that issue and link the new PR to it (multiple PRs can be linked to one issue).
• Issues that introduce changes must be added to the project board and move through the appropriate columns.
• If an issue does not introduce a change in the repository (e.g., meeting agendas), it doesn’t need to be added to the project board.
• Always assign one or more owners to an issue.
• Add appropriate labels and issue types.
• Assign a milestone if the issue is related to a milestone activity—even if it’s from a previous one.
• Close the issue once it is complete.

🔹 Pull Requests (PRs)

• Assignee: Assign an owner.
• Reviewers: If unsure, assign all group members. If a specific member is responsible for reviewing, assign only that person.
• Labels: Apply relevant PR labels.
• Milestone: Tag the PR with the related milestone (even if it's a past one).
• Follow the PR checklist/template.
• Do not link PRs directly to the project board. A PR is always linked to an issue in the board.
• Delete the branch after the PR has been merged.

---

📋 Project Board Guidelines

• Only add issues, not PRs, to the project board to maintain clarity.
• Move issues through the board columns as their status progresses.

---

🧾 Naming Conventions

To ensure clarity and traceability, we use action-oriented naming: use a verb + object structure in the present tense (not continuous). This makes tasks understandable at a glance and easy to follow later.

🔸 Commit Messages

• Use all lowercase.
• Be specific and action-oriented.
• Example:
  • ✅ add group norms
  • ✅ resize system thinking schematic image
  • ❌ update group norms → Instead: add 2 extra norms, fix spelling in group norms document

🔸 Branch Names

• Use lowercase with hyphens (-) instead of underscores (_).
• Be as specific as possible; doesn’t need to match the commit message exactly.
• Example:
  • ✅ add-group-norms
  • ❌ add_group_norms

🔸 Issue and PR Titles

• Use sentence case (capitalize only the first word).
• Make the title descriptive enough to stand on its own—no need for extra explanation if the title is well-written.
• Example:
  • ✅ Add research question
  • ❌ Research question (not action-based)

🔸 Descriptions

• Use bullet points if extra explanation is needed.
• For example, if a PR does several changes beyond the title, briefly list them.
• You can overwrite the default PR template description at the top (not the checklist) with a more relevant summary.

🔸 Naming Consistency (for simple tasks)

If the task is simple (e.g., a one-commit change), it’s perfectly fine to keep the same name across commit message, branch, PR, and issue:

Type	Example
Commit message	add research question
Branch name	add-research-question
PR Title	Add research question
Issue Title	Add research question

⚠️ These naming conventions apply only to tasks that affect the repository.

[linahKhayri]

Good job Salih! I think all the convention points you raised are solid. If everyone agrees, feel free to go ahead and add them to the Contributors Guidelines under the relevant section.

[salihakalender]

@Adamx090 Thank you Great work! All convention points are strong and clear.

[FalaqMajeed]

@Adamx090 Thank You for your effort! the conventions are great, feel free to add them right away

[Husayn01]

@Adamx090 Great job, this looks fine, it's detailed and exhaustive