Skip to content

Commit ec45d90

Browse files
vickabirevickabire
committed
(docs) Add pull request tips to the documentation
1 parent fb99a5b commit ec45d90

File tree

3 files changed

+200
-1
lines changed

3 files changed

+200
-1
lines changed

‎.github/workflows/pr-guidelines-reminder.yml‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
name: PR Guidelines Checker
2+
3+
on: pull_request_target
4+
5+
jobs:
6+
check-guidelines:
7+
runs-on: ubuntu-latest
8+
steps:
9+
- name: Check PR Guidelines
10+
uses: actions/github-script@v7
11+
with:
12+
script: |
13+
const { owner, repo } = context.repo;
14+
const pr = context.payload.pull_request;
15+
16+
let errors = [];
17+
18+
const branchName = pr.head.ref;
19+
if (!branchName.match(/^issue-\d+$/)) {
20+
errors.push("❌ Branch name should follow format 'issue-NUMBER' (e.g., issue-123)");
21+
}
22+
23+
const titlePattern = /^(Fix|Fixes|Close|Closes|Resolve|Resolves) #\d+:/i;
24+
if (!pr.title.match(titlePattern)) {
25+
errors.push("❌ PR title should start with 'Fix #NUMBER:' (e.g., 'Fix #123: Add feature')");
26+
}
27+
28+
const hasIssueReference = pr.body.includes('#') && /\#\d+/.test(pr.body);
29+
if (!hasIssueReference) {
30+
errors.push("❌ PR description should reference an issue number (e.g., #123)");
31+
}
32+
33+
const checkConclusion = errors.length === 0 ? 'success' : 'failure';
34+
const checkOutput = {
35+
title: 'PR Guidelines Check',
36+
summary: errors.length === 0
37+
? '✅ All PR guidelines checks passed!'
38+
: '❌ Some checks failed:\n\n' + errors.join('\n')
39+
};
40+
41+
if (errors.length > 0) {
42+
const guidelinesUrl = `https://github.com/${owner}/${repo}/blob/develop/PULL_REQUEST_TIPS.md`;
43+
const comment = `## PR Guidelines Check Failed
44+
45+
Please fix the following issues:
46+
47+
${errors.join('\n')}
48+
49+
Please review our [Pull Request Guidelines](${guidelinesUrl}) for more details.`;
50+
51+
await github.rest.issues.createComment({
52+
issue_number: context.issue.number,
53+
owner: context.repo.owner,
54+
repo: context.repo.repo,
55+
body: comment
56+
});
57+
}
58+
59+
await github.rest.checks.create({
60+
owner,
61+
repo,
62+
name: 'PR Guidelines Check',
63+
head_sha: pr.head.sha,
64+
status: 'completed',
65+
conclusion: checkConclusion,
66+
output: checkOutput
67+
});

‎PULL_REQUEST_TIPS.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Pull Request Guidelines
2+
3+
Before submitting a pull request, please ensure you follow these important
4+
guidelines:
5+
6+
## 1. GitHub Issue Requirements
7+
8+
- Ensure you have a GitHub issue for your changes (except for trivial typo
9+
fixes)
10+
- Check existing issues to avoid duplicates
11+
- Wait for issue assessment and confirmation before starting work
12+
- Assign the issue to yourself when you start working to prevent duplicate
13+
efforts
14+
15+
## 2. Branch Naming
16+
17+
- Branch name should reference issue number (e.g., issue-123)
18+
- Create new branches from updated develop:
19+
```bash
20+
git checkout develop
21+
git checkout -b issue-123
22+
```
23+
24+
## 3. Pull Request References
25+
26+
- PR title must include issue number (e.g., "Fix #123: Improve error handling")
27+
- Include issue link in PR description
28+
- Title should clearly summarize the changes
29+
30+
## 4. Target Branch
31+
32+
- Always create PRs against the develop branch unless specified otherwise
33+
- Reviewers will handle backporting to other branches if needed
34+
35+
## 5. Keep Updated
36+
37+
- Pull latest changes before submitting PR:
38+
```bash
39+
git pull --rebase upstream develop
40+
```
41+
- Run this daily when working on longer tickets
42+
43+
## 6. Formating the Source code after making changes
44+
45+
1. After making UI changes to the [frontend](./frontend/) directory , run the
46+
formatter to properly format the Frontend code
47+
48+
cd frontend
49+
npm run format
50+
51+
2. After making changes to the [backend](./src/) directory, run the formatter
52+
to properly format the Java code
53+
54+
mvn spotless:apply
55+
56+
## 7. Code Conventions
57+
58+
- Follow project coding conventions
59+
- Configure IDE according to project guidelines
60+
- Review your diff carefully before committing
61+
62+
## 8. Clean Pull Requests
63+
64+
- Keep changes focused and related to the issue at hand
65+
- Avoid mixing unrelated changes in a single PR
66+
- Example of what NOT to do:
67+
```
68+
// Bad: Single PR with unrelated changes
69+
- Refactor utils class
70+
- Improve UI responsiveness in multiple components
71+
- Fix typos in documentation
72+
```
73+
- Instead, split into separate PRs:
74+
```
75+
// Good: Separate PRs for each concern
76+
PR #1: "Fix #123: Refactor utils class"
77+
PR #2: "Fix #124: Improve UI component responsiveness"
78+
PR #3: "Fix #125: Fix documentation typos"
79+
```
80+
- Consider squashing commits for bug fixes and small features
81+
- Don't worry about squashing review-related commits
82+
- Final squash will be handled during merge
83+
84+
## 9. Descriptive Messages
85+
86+
- Use meaningful PR descriptions
87+
- Include issue number and purpose
88+
- When in doubt, use the issue summary
89+
90+
## 10. Review Process
91+
92+
- Request review from appropriate team members
93+
- Add PR URL as comment on the issue
94+
- Address review comments promptly
95+
96+
## 11. UI Changes
97+
98+
- Attach screenshots to PR description or comments
99+
- Include before/after images for visual changes
100+
- For web apps, include preview links if possible
101+
102+
## 12. Single Pull Request
103+
104+
- Maintain one PR per issue
105+
- Push new commits to same branch to update PR
106+
- Only create new PR if original cannot be modified
107+
108+
## 13. Replacing Pull Requests
109+
110+
- Close old PR with explanation if creating new one
111+
- Reference new PR in closing comment
112+
113+
## 14. Abandoning Work
114+
115+
- Unassign yourself from issue if stopping work
116+
- Document useful findings in issue comments
117+
- Close any open PRs with explanation
118+
119+
## 15. Build Verification
120+
121+
- Check GitHub Actions build status
122+
- Investigate failures using "Details" link
123+
- Run `mvn clean install` locally before pushing
124+
125+
Remember to review the "Using Git" documentation, particularly the "Submit the
126+
code" section, before creating pull requests.

‎README.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ see [OpenELIS-Docker setup](https://github.com/I-TECH-UW/openelis-docker)
7979

8080
docker-compose -f dev.docker-compose.yml up -d --no-deps --force-recreate oe.openelis.org
8181

82-
#### The Instaces can be accesed at
82+
#### The Instances can be accessed at
8383

8484
| Instance | URL | credentials (user : password) |
8585
| ------------ | :-------------------------------------: | ----------------------------: |
@@ -106,3 +106,9 @@ accessing any of these links, simply follow these steps:
106106
to properly format the Java code
107107

108108
mvn spotless:apply
109+
110+
### Pull request guidelines
111+
112+
Please follow the [pull request tips](PULL_REQUEST_TIPS.md) in order to make
113+
life easy for the code reviewers by having a well defined and clean pull
114+
request.

0 commit comments

Comments
 (0)