Enhancing Contribution and Developer Guidelines

[AleksandarCole]

Problem Statement

Our current contribution guidelines are very basic and lack the detailed information developers need to effectively contribute to the project. We need comprehensive documentation that covers all aspects of the development process, coding standards, and architectural decisions.

Current State

• Basic contribution guidelines that don't provide enough direction
• Missing developer-focused documentation
• No clear coding standards or best practices documentation
• Lack of UI style guide for frontend development
• No Architecture Decision Records (ADRs) to explain key technical decisions

Desired Outcome

Comprehensive documentation that includes:

• Detailed contribution guidelines
• Complete developer guidelines covering the entire development process
• Clear standards for code, commits, branches, and PRs
• UI style guide for consistent design (figure out how to utilize the existing app-design repo)
• Architecture documentation including ADRs

Discussion Points

• What should our enhanced contribution guidelines include?

  • Workflow for contributors
  • Communication channels
  • Issue and PR processes
  • Review expectations

• What should be covered in the developer guidelines?

  • Environment setup
  • Build, test, and run instructions
  • Branch, PR, and commit naming conventions
  • Code organization

• What coding standards and best practices should we document?

  • Language-specific guidelines
  • Testing requirements
  • Documentation requirements
  • Performance considerations

• What should our UI style guide contain?

  • Design principles
  • Component library usage
  • Responsive design guidelines

• How should we implement Architecture Decision Records?

  • Format and template
  • Process for creating new ADRs
  • Storage and organization
  • Key architectural decisions to document first

Next Steps

Let's prioritize the documentation needs and create a plan for developing these guidelines in stages, focusing first on the most critical information needed by new contributors.

[AleksandarCole]

After discussion with @VeljkoMaksimovic, we agreed that he will review and fully update our contribution and developer guidelines.

Guidelines Content

These guidelines should give contributors clarity on:

• Zoomed out overview of Semaphore architecture and services
• Instructions on how to build, test and troubleshoot
• How to properly submit PRs along with any naming conventions etc.
• How things are approved/verified/merged
• How releases are managed

Acceptance Criteria

• We will use our support team as the litmus test for these guidelines
• Our support team should be able to contribute small changes like fixing typos purely based on the contribution guide
• There should be 0 issues/irregularities with external contributions
• Ideally, a large part of the process should be automated/enforced through GitHub tools/templates/actions

[AleksandarCole]

Issue was opened and added in scope for 1.3 release closing the discussion.
#337