Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 6 Next »

Fundamentally a Pull Request is simply a request for another dev to review work before committing it to a code repository and publishing it. At Kalamuna, the process involves the original developer(s) who worked on the task (the author); another developer who reviews the task for quality and completeness; and ideally a Project Manager to provide a Quality Assurance check. These steps are necessary to ensure that Kalamuna continues to provide high-quality, version-controlled code that follows our best practices.

PR Process

  1. Dev completes work on a Jira ticket and assigns it to a reviewer in JIRA

  2. Dev creates Pull Request for the reviewer in GitHub following best practices below

  3. Reviewer pulls the branch locally, tests per the ticket guidelines, and verifies it works as expected

  4. Reviewer adds notes to the ticket on how to QA it (links to relevant pages on dev where the change appears, how to check to see if it’s working, etc)

  5. Reviewer assigns ticket to PM for QA review

  6. PM reviews the outcome to ensure it accomplishes the client’s goals

    1. If approved, PM contacts the client for approval or updates

    2. If not approved, PM documents the issue(s) and reassigns to the reviewer

  7. Once client approval is received, code is merged to the main branch and deployed

Responsibilities

  • The Author: The author of the PR has the responsibility and room to make sure the PR is clear and approachable to other team members so that they can give a confident review.

    1. Provide context to what brought about the Pull Request

    2. Provide a summary of the problem the Pull Request is solving

    3. Provide a summary of the solution that the Pull Request provides

  • The Reviewer: The reviewer of a PR has the responsibility to unblock the work of the author. They do this by approving the pull request, or by requesting needed changes and providing explicit feedback when necessary. No matter which way the review goes, it’s crucial that the review is timely so that they don’t block and frustrate their team members.

    1. Unblocking the PR author

    2. Validate the code: Make sure that the code in the PR looks like it is doing what the author intended it to do. This includes ensuring that there is proper testing.

    3. Provide good feedback, which should include the following:

      • Clear, actionable advice with examples of what (if anything) should be changed.

      • Reasons for why the changes have been suggested, with documentation or evidence that supports that point of view.

      • An impersonal tone, so the review does not feel like overt criticism.

    4. Do all this in a reasonable amount of time

  • The Team Itself: Good PR practices are helpful at an individual level, but to be most effective, the team should agree on and adopt a set of standards that the team can collectively hold PRs to.

    1. Decide a reasonable time table

    2. Decide what should be blocking vs non-blocking

      • Blocking

        • Bugs: This could be “This code will error when X happens. X happens often”

        • Untested code changes: How do we know if the code works if we can’t verify it?

        • Hard-to-Comprehend code: When a section of code is hard to read and hard to understand what it’s doing, it adds uncertainty to the code as well as a maintenance burden if it ever needs changes. We decided that’s a good enough reason to block code.

      • Non-blocking

        • Code styles: This is stuff like “could use .map here”. I call these “code flavors” because there is more than one way to do things and everyone has their own preference on what’s more “readable”.

        • Improvements: - This is stuff like, “What if we extracted this out to its own method/class?”

        • Opinions as Standards - Some people hold certain coding authors and their rules to a high standard. I love and take inspiration from some book authors, but I think that it’s important to see their recommendations as best practice opinions rather than rules to follow. Because of that, I find comments to follow those patterns as code styles and improvements and therefore non-blocking.

Best Practices

  1. Respect People's Time

  2. Always Provide Constructive Feedback

  3. Keep Your Ego Out of Code Reviews

    1. Reasons not feelings

    2. Be open to other ways of doing things

  4. Be Precise About What Needs to be Improved

  5. Don't Just Hope for the Code to Work

  6. Reinforce Code Submission Best Practices

  7. Be Strict About Temporary Code

  8. Check the Project’s Satellite Files (documentation, etc)

  9. Visualize the Bigger Picture

  10. Title the Pull Requests clearly, linking to the original JIRA issue if possible

    1. For example: PROJ-123: Description

  11. Provide a clear description of what is accomplished with the code change in the Pull Request, and link to the original JIRA issue when possible. For example:

    1. This change turns the button color GREEN, because RED wasn’t very user friendly.### References- PROJ-123 - Getting issue details... STATUS

  12. For small 1-5 line inline changes use GitHub’s inline comments feature, along with inline suggestions. For example… The button size should be 5 instead of 3. ``` suggestion $buttonSize = 5; ```

To Consider

  • When is a PR appropriate

  • Who is responsible for resolving merge conflicts

  • Goal of knowledge sharing as much as “approval”

  • How to prioritize/review style guide issues

  • Be generous of spirit – the goal is to produce code that works for functional web sites.

References

  • No labels