Development Process: Norms and Best Practices

Background: See this discussion for more context. This page is a first attempt at capturing development norms and best-practices for Stacks blockchain developers, based on input from past and current contributors.

Task Scoping

• Most tasks should be scoped such that they can be completed in 3-5 days.
• Larger tasks should be broken down into smaller chunks before work begins. Any exceptions to this should be documented in the task.

Repository Scope

• Anything that doesn’t absolutely need to be in the stacks-blockchain should default to separate repos.

Pull Requests

• Well-scoped tasks should result in well-scoped PRs.
• Reviewers are expected to provide feedback within 24 hours in the common case, and before 2 days in almost all cases.
• If a reviewer is unable to provide feedback in 2 days, they should inform the PR author.
• If the delay is because a PR is too large or complex, PR authors are responsible to either simplify the PR or ensure reviewers have sufficient context to do a timely review (e.g. via a code walk-through)

Pull Requests from External Contributors

• PRs from contributors without maintenance privileges are encouraged! However, they do require special handling.
• After review succeeds on an external PR, a stacks-blockchain repo maintainer must be assigned as an owner for the PR.
• The assigned repo maintainer is responsible for:
  • Creating a new branch in the stacks-blockchain repo (e.g., feat/external-pr-4517)
  • Setting the external PR's target branch to the new branch (e.g., feat/external-pr-4517)
  • Merging the external PR into the target branch. This will close the external PR as "merged".
  • Opening a PR from the new target branch (e.g., feat/external-pr-4517) to the appropriate target (e.g., develop)
  • Tagging reviewers and then merging the new PR