Code review

The principles and reasoning for code reviews are laid out in the General principles section of the Epiverse-TRACE blueprints. This section explores more of the technical details around conducting a productive code review.

The ways of working for code reviews within Epiverse-TRACE packages follows many of the guidelines covered in the Tidyteam code review principles. Instead of repeating all of the information from the Tidyteams documents here we highlight a few areas of similarity between the Tidyteam and Epiverse-TRACE for clarity.

• Code reviews take place on Github pull requests to provide a transparent and open platform for people to engage with package reviews.
• Progress over perfection: accept pull requests which better the code without needing to be perfect to prevent slowdowns.
• Adhere to the established code style. This is automatically checked by the lintr continuous integration workflow
• When changes are non-trivial test out new changes locally. This is especially important if the changes are user-facing.
• To enable agile development PRs should be swiftly, but thoroughly, reviewed. The pace of code review is predominantly influenced by the size of the PR, so but keeping changes in PRs functionality small and focused, will enable the team to review and close PRs and keep momentum with development.
• Use suggestions when beneficial, for example typos, to allow the PR author to easily apply changes through commits directly in Github.
• Take advantage of Github’s keyword mechanism to reference and close issues through commits and then refer to these in the description of the PR.
• Once a conversation on a PR is resolved, the “Resolve conversation” button can collapse that specific discussion. The PR author should resolve conversations. It is good practice to add a comment with a link to the commit SHA (which can be copied from Github commit history) to let those involved in the conversation know where the changes were applied. In the case a PR author misses resolving a conversation but has messaged with the commit SHA the PR reviewer can resolve it. Additionally, it is perfectly reasonable to merge an approved PR with some conversations left open, assuming they have been addressed in the PR.

One difference to highlight between the Tidyteam principles and Epiverse-TRACE is not directly related to code reviews and more to merging strategies. Within Epiverse-TRACE we prefer rebase and merge, to maintain a linear commit history, over the tidyverse preference of squash and merge.

Reviewers can be assigned in Github. Those assigned should review at their earliest convenience or notify the PR author assigning them that they are unable to review. It is not mandatory for reviewers to be assigned, and reviewing a PR without being assigned can help the PR author complete the merge sooner.

It is left to the maintainer or one of the authors of a package to merge the PR once reviewed. This ensures that code quality is maintained throughout development. The maintainer may be the PR author, in the case of requesting a code review from another member of the team, or may be the PR reviewer, when PR is opened by a contributor. PR authors cannot approve their own PRs even if they are the package maintainer.

Code review can be skipped in cases when the package maintainer or authors makes minimal changes, these include, but are not limited to: not touching user-facing functions, only changing package accessories (e.g. Github actions) or minor documentation fixes. In these cases a “Merge without waiting for requirements to be met (bypass branch protections)” option can be ticked and the PR can be merged. For more information on merging see the Standards for branching and merging.

If suggested changes fall outside the scope of the PR, utilise Github’s feature of generating issues from PR comments. Clicking the ellipsis in the PR comment and selecting “Reference in new issue” will open an issue with reference to the PR.