Skip to content

Development overview

Agorakit is proudly a hypermedia app. We use PHP with Laravel and follows its best practices on the backend. However, we use Unpoly for UI interactivity, flat CSS (no build), and Bootstrap-flavored tabler.io.

Tip

Verify the AGPLv3 licence fits your needs.

Warning

Before coding: Review the roadmap, then propose & discuss changes on the community.

Quality tools

To maintain code quality, we use:

Conventions

To enable clear communication between stakeholders, we use:

Code review

We require peer code reviews both to maintain quality and socialize changes. To enable faster acceptance of code changes, we follow these practices.

Code structure

These checks increase safety and make code review more effective.

  1. NEVER combine functional changes with coding standards updates nor environment changes (like CI config). Give each their own pull request.
  2. New functions & methods MUST have only one purpose. This makes them clear, testable, and safe.
  3. ALWAYS use descriptive branch names (e.g. fix/some-name or feat/new-thing).

Pull request basics

Skipping these steps wastes other peoples' time. Everyone should always do them when contributing code.

  1. Write descriptive titles in the imperative mood (e.g. "Fix the thing", "Update the widget"). If this is difficult, the PR may be too broad.
  2. Cross-reference ALL related PRs, issues, discussions, or docs with a link.
  3. Verify:
    1. Target branch (usually main).
    2. Code diff is what you intended.
    3. Quality checks pass in the CI pipeline.
  4. If not immediately ready for review, make it a draft.

Advanced pull request authoring

Writing exception pull requests leads to faster development, less debugging, and more cohesive teams.

  1. Summary: For longer PRs, start by briefly summarize the entire process (initial challenge to solution) in a sentence or two. This especially helps project leads understand what you've done even if they lack the time to dive into details.
  2. Goals: What are we trying to accomplish? You should understand our higher-level goals and discuss how your changes align with them, or document in the code why they do not. Link to any relevant work items or discussions.
  3. Solution: What other solutions did you consider and why did you choose this one? This helps other developers learn from or mentor you, and provides a great log for future considerations.
  4. Methodology: Why did you implement the solution you chose this way? You can even lead the reviewer thru your code choices like a tour by commenting on lines of your own PR.
  5. Potential: What future work could be done, and how important is it? Does it warrant writing follow-up issues?
  6. History: Correct & condense your commit history with git rebase to make it easier to understand. Exemplary commit histories present a logical story. Adding PR comments between batches of commits can add further narrative.

How in-depth you discuss each of these items in a pull request will vary greatly depending on scope and experience.

AI coding assistance

At this time, we have not seen evidence that AI is capable of producing code reviews as requested above. Therefore, we strongly discourage the use of AI in code contributions to this project unless under the careful supervision of a senior software engineer with sufficient experience to revise & contextualize its assistance. We will close pull requests that appear to have been primarily created with generative AI tools due to requiring excessive review time.