DOCS - Contributing with code

[zzap]

This issue aims to define best practices for contributing code to the FIAR project as part of documenting the project's workflow definitions. What I'm giving here is a mere proposal, a starting point, a list from which we can remove or add items.

Proposed best practice and workflow

Naming branches

Maybe an open-source project doesn't need to go that far to adopt a branch naming convention, but it is a good way to avoid a bunch of branches named after GitHub usernames. A very simple requirement could be using the issue name for it.
Example:

• issue: Automate Checking with AspireCloud #160
• branch: 160-automate-checking-with-aspirecloud

Pull requests

• Every pull request must have an associated issue.
• Every pull request should have the following information:
  • Appropriate description of what the code does.
  • How does it do it.
  • Steps to test.
  • Which issue is it closing/fixing (by applying the appropriate keyword, given the repo has auto-closing enabled).
• A single pull request should aim to be as small as possible for a couple of reasons: easier for code review, easier to spot potential bugs.
• If the feature requires a larger number of code changes, it is preferable to split changes into smaller logical chunks (commits) and request a pre-review if possible.
• Pull requests that are not ready for review yet should be marked as such by adding [WIP] (work in progress) before the title or converting it to Draft (given that the repo supports draft pull requests).
• PR is considered active as long as there is activity within 7 days. After 7 days of inactivity, the bot can remind the contributor to provide an update. If another 7 days of inactivity pass, the PR (and associated issue) is considered abandoned/stalled.

Issues

• Issues should follow pre-made templates (given that they exist).
• Every issue should have the following information:
  • Description of the problem.
  • A place where the problem occurs (URL or screen in the dashboard).
  • Software info (e.g. plugin version, WordPress version, etc.).
  • Steps to reproduce the problem.
  • Expected behaviour.
  • Proposed solution (optional).
• Issue's status should reflect the current state (In progress, Review, Done, etc.) - easily automated with GitHub workflows.
• Issue's assignee should be the person who actively works on (existing) PR.

Examples of workflow

Small successful PR

• Contributor finds the issue they want to work on. They state it in the comment (for GitHub orgs, this may be the only way to assign someone outside the org) or are assigned by a maintainer upon request (it's also important to define where and how this request can be made).
• Contributor creates a new branch (in their local from updated main in clone or fork).
• Contributor works on a code, pushes, and creates a pull request.
• Contributor writes down all the necessary info in PR description.
• Contributor requests review.
• Reviewer may or may not require changes to the PR, which are expected to be responded to within a window of 7 days (not completed, but responded to).
• Reviewer approves changes and adds a milestone to the PR.
• PR gets merged (automatically closing the issue) and deployed.

Large successful PR

• Contributor finds the issue they want to work on. They state it in the comment (for GitHub orgs, this may be the only way to assign someone outside the org) or are assigned by a maintainer upon request (it's also important to define where and how this request can be made).
• Contributor creates a new branch (in their local from updated main in clone or fork).
• Contributor works on a code, pushes a commit, and creates a pull request.
• Contributor marks PR as work in progress, or converts to a draft.
• If needed, or in doubt, a contributor can request a pre-review of already completed code, and/or start a discussion in comments about the best approach.
• Contributor writes down all the necessary info in PR description.
• When complete, the contributor removes the work in progress mark and requests a review.
• Reviewer may or may not require changes to the PR, which are expected to be responded to within a window of 7 days (not completed, but responded to).
• Reviewer approves changes and adds a milestone to the PR.
• PR gets merged (automatically closing the issue) and deployed.

Abandoned PR

• Contributor finds the issue they want to work on. They state it in the comment (for GitHub orgs, this may be the only way to assign someone outside the org) or are assigned by a maintainer upon request (it's also important to define where and how this request can be made).
• Contributor creates a new branch (in their local from updated main in clone or fork).
• Contributor works on a code, pushes, and creates a pull request.
• From this moment, at any point contributor fails to respond within 14 days (even after a ping from a bot)
• PR is automatically marked as stalled (for 7 days). The associated issue is automatically back to To Do status.
• If no one takes over within these 7 days, PR gets automatically closed.