Repository navigation
[NoQA] docs: add PR authoring & reviewing standards and best practices guide - #80839
Conversation
|
@youssef-lr Please copy/paste the Reviewer Checklist from here into a new comment on this PR and complete it. If you have the K2 extension, you can simply click: [this button] |
| | **Minor lint issues** | Note in review, let Author fix in final pass | | ||
| | **Merge conflicts** | Review logic/code, Author resolves conflicts after | | ||
| | **Unrelated failing workflows** | Continue review if failure is clearly not from this PR | | ||
| | **Pre-existing console errors** | Report in Slack `#expensify-bugs`, don't block PR | |
There was a problem hiding this comment.
Is this for the contributor or C+? If they former they don't have access to #expensify-bugs
There was a problem hiding this comment.
C+ Reviewers, will add a change to make this clear 👍
| | Role | Primary Responsibility | | ||
| |------|----------------------| | ||
| | **PR Author** | Owns the correctness, quality, and testing of their changes. Must demonstrate a clear understanding of what was changed and why. | | ||
| | **C+ Reviewer** | Acts as the final safety net. Validates proper testing, catches edge cases, and ensures code quality standards are met. | |
There was a problem hiding this comment.
Maybe we could add a row for the internal engineer? Something like:
Internal authority to ensure code is secure, compliant, not malicious, or propagating bad code patterns.
|
|
||
| ## PR Title Convention | ||
|
|
||
| All PR titles should follow a consistent format to improve clarity, searchability, and deploy tracking. |
There was a problem hiding this comment.
We should consider adding this to the AI reviewer rules.
There was a problem hiding this comment.
Agreed - should be done after this doc is merged to slowly start enforcing some of the important items listed here.
|
|
||
| ## Explanation of Change | ||
|
|
||
| **Every PR must include an "Explanation of Change" section**, even if the intent seems obvious from the title. |
There was a problem hiding this comment.
Consider adding:
The best explanations will explain why the change is being done, not just what is changing.
|
|
||
| | Requirement | Description | | ||
| |------------|-------------| | ||
| | ✅ Manual tests documented | Clear, step-by-step testing instructions | |
There was a problem hiding this comment.
| | ✅ Manual tests documented | Clear, step-by-step testing instructions | | |
| | ✅ Manual and QA tests documented | Clear, step-by-step testing instructions | |
| Before requesting review, the Author must: | ||
| 1. Run the app locally and verify the fix on **all platforms** (Web, iOS, Android, mWeb) | ||
| 2. Document specific flows affected by the change | ||
| 3. Provide comprehensive manual test steps |
There was a problem hiding this comment.
| 3. Provide comprehensive manual test steps | |
| 3. Provide comprehensive manual and QA test steps |
| |------|-------------| | ||
| | **Primary Verification** | Confirm the fix/feature works as intended (happy path) | | ||
| | **Basic Regression Testing** | Verify existing flows still work | | ||
| | **Unit Test Coverage** | Add tests to prevent future regressions | |
There was a problem hiding this comment.
Should this mention something about unit tests for both the positive and negative flows? Such as: test when a parameter exists, and when it doesn't exist. Or test when a boolean is true AND false.
| 2. Document specific flows affected by the change | ||
| 3. Provide comprehensive manual test steps | ||
| 4. Ensure unit tests cover the changed logic | ||
| 5. Verify CI is green (tests, lint, type checks) |
There was a problem hiding this comment.
Should we mention something about responding to any AI reviewer comments and resolving/dismissing them all?
| | **Merge conflicts** | Review logic/code, Author resolves conflicts after | | ||
| | **Unrelated failing workflows** | Continue review if failure is clearly not from this PR | | ||
| | **Pre-existing console errors** | Report in Slack `#expensify-bugs`, don't block PR | | ||
|
|
There was a problem hiding this comment.
Maybe we could say something here that if a reviewr's comment starts with "NAB" that it stands for "Not a blocker" so the author knows that it's their decision whether or not to make the change.
| - The author cannot confidently explain every change | ||
| - Testing becomes unwieldy or impossible to cover comprehensively | ||
| - Multiple unrelated changes are bundled together | ||
| - The diff is difficult to review in one sitting (rule of thumb: 400+ lines of logic) |
There was a problem hiding this comment.
Maybe something about number of files too? When I see 20+ files changed I start to 😬
There was a problem hiding this comment.
Makes sense, will mention: excluding files like translations / types, with more focus on extensive logic changes in 20+ files changed.
|
@tgolen All comments addressed ✅ Let me know if there's anything else! |
| ### Copy/Translation Changes | ||
|
|
||
| **Primary Focus**: Ensuring proper localization and translation approval | ||
|
|
||
| When a PR adds or modifies user-facing copy that requires translation, the Author must follow this workflow: | ||
|
|
||
| | Step | Action | | ||
| |------|--------| | ||
| | 1 | **Search for similar strings** in `src/languages/*` to maintain consistency | | ||
| | 2 | **Get Spanish translation** using [JaimeGPT](https://chatgpt.com/g/g-2dgOQl5VM-english-to-spanish-translator-aka-jaimegpt) | | ||
| | 3 | **Gather screenshots** showing where the proposed copy appears in the product | | ||
| | 4 | **Post in [`#expensify-open-source`](https://expensify.enterprise.slack.com/archives/C01GTK53T8Q)** with all the above for internal approval | | ||
| | 5 | **Link the Slack message** in your PR for reference | | ||
|
|
||
| > [!IMPORTANT] | ||
| > Translation approval from Expensify internal team is required before the PR can be merged. |
There was a problem hiding this comment.
@mallenexpensify Added this based on your request from Slack.
There was a problem hiding this comment.
Would it be helpful to hyperlink "JaimeGPT and "Search language files" ?
There was a problem hiding this comment.
NABish but this manual process hopefully won't exist for much longer and we can start auto-translating Español
|
@tgolen 🟢 I think we're good to merge here after latest discussions on Slack. |
Reviewer Checklist
Screenshots/VideosAndroid: HybridAppAndroid: mWeb ChromeiOS: HybridAppiOS: mWeb SafariMacOS: Chrome / Safari |
|
🚀 Deployed to staging by https://github.com/tgolen in version: 9.3.13-1 🚀
|
|
🚀 Deployed to staging by https://github.com/tgolen in version: 9.3.15-0 🚀
|
|
🚀 Deployed to production by https://github.com/lakchote in version: 9.3.15-10 🚀
|
Explanation of Change
As a result of this Slack discussion, this PR adds a new contributor guide (
PR_AUTHOR_REVIEWER_BEST_PRACTICES.md) that defines the shared "playbook" for day-to-day standards between PR Authors and C+ Reviewers. The document builds upon existing guidelines and clarifies:fix:,feat:,refactor:) for improved searchability and deploy blocker tracking.↪️ Additionally, cross-references to the new guide were added to:
CONTRIBUTING.md– Step 19 in the "Submit your pull request for final review" section.PR_REVIEW_GUIDELINES.md– Introduction paragraph linking to the comprehensive best practices.HOW_TO_BECOME_A_CONTRIBUTOR_PLUS.md– Added as a requirement for C+ candidates.@tgolen @mallenexpensify
Fixed Issues
$
PROPOSAL:
Tests
N/A
Offline tests
N/A
QA Steps
N/A
PR Author Checklist
### Fixed Issuessection aboveTestssectionOffline stepssectionQA stepssectioncanBeMissingparam foruseOnyxtoggleReportand notonIconClick)src/languages/*files and using the translation methodSTYLE.md) were followedAvatar, I verified the components usingAvatarare working as expected)StyleUtils.getBackgroundAndBorderStyle(theme.componentBG))npm run compress-svg)Avataris modified, I verified thatAvataris working as expected in all cases)Designlabel and/or tagged@Expensify/designso the design team can review the changes.ScrollViewcomponent to make it scrollable when more elements are added to the page.mainbranch was merged into this PR after a review, I tested again and verified the outcome was still expected according to theTeststeps.