|
| 1 | +# CONTRIBUTION GUIDELINES FOR PBENCH |
| 2 | + |
| 3 | +## 1. Forking the repository: |
| 4 | + |
| 5 | + |
| 6 | +Forking a repository allows you to freely experiment with changes without affecting the original project. Most commonly, forks are used to either propose changes to someone else's project or to use someone else's project as a starting point for your own idea. |
| 7 | + |
| 8 | +## 2. Cloning |
| 9 | +Cloning is used to create a local copy of the repository. It takes only one command in the terminal to clone the repository. |
| 10 | +git clone https://github.com/distributed-system-analysis/pbench.git |
| 11 | +## 3. Choosing an issue to work upon |
| 12 | +1. Go to the issues section, to find a list of open issues. |
| 13 | + |
| 14 | + |
| 15 | + |
| 16 | +2. Select the issues you are interested to work upon based upon the labels and descriptions. |
| 17 | + |
| 18 | +3. It is a good practice to assign the issue to yourself to let others know you're working upon it. |
| 19 | + |
| 20 | +## Making changes to the codebase |
| 21 | +- Follow the instructions in the README.md to setup and install pbench. |
| 22 | +- Follow the instruction in the README.md to use web server (PBench Dashboard) |
| 23 | +- Save your changes by creating own local branches on git |
| 24 | +- While doing the changes, follow the style guides: |
| 25 | + - JavaScript: https://github.com/airbnb/javascript |
| 26 | + - React: https://github.com/airbnb/javascript/tree/master/react |
| 27 | + - CSS: https://github.com/airbnb/javascript/tree/master/css-in-javascript |
| 28 | + |
| 29 | +## Add, Commit and Push |
| 30 | +- Follow these commands to push the changes to your branch. |
| 31 | +``` |
| 32 | +git add . |
| 33 | +git commit -m "Issue solved" |
| 34 | +git push origin branch_name |
| 35 | +``` |
| 36 | + |
| 37 | +## Conventions on commits, PRs, and overall git best practices. |
| 38 | +- Commit messages should have a short description (50 - 70 characters) followed by a longer format description of the changes below if needed. You’ll also notice each line is formatted for a specific length in the longer format description. For example: |
| 39 | +Extend auditing to incoming, results, and users |
| 40 | + |
| 41 | +``` |
| 42 | +The server audit is now applied to the incoming, results, and users |
| 43 | +directory hierarchies. Any unpacked tar ball should now be compre- |
| 44 | +hensively checked to see that all is in the correct place. |
| 45 | +
|
| 46 | +The test-20 unit test gold file holds an example of an audit report |
| 47 | +covering all the possible outputs it can emit. Each unit test runs |
| 48 | +the report as well, and they have been updated accordingly. |
| 49 | +``` |
| 50 | +- For more on best practices, check out this article for reference from time to time: https://www.git-tower.com/learn/git/ebook/en/command-line/appendix/best-practices |
| 51 | +## Opening a pull request |
| 52 | +1. **If there are multiple commits, Squash down the commits to one** |
| 53 | +2. Commit the changes. |
| 54 | +3. Click on New Pull Request |
| 55 | +4. Write appropriate Pull Request Title stating the fix. |
| 56 | + a. Use present tense (ex. Fixes, Changes, Fixing, Changing..) |
| 57 | +5. References the issue that the PR is fixing with **“Fixes #issue_number”** in the description. |
| 58 | +6. Provide a detailed description (at least 50 - 70 characters) of the changes.(If UI, add screenshots or gif) |
| 59 | +7. Make sure that the branches can be automatically merged(otherwise rebase the PR with master) and then click : Create pull request . |
| 60 | + |
| 61 | + |
| 62 | +8. Assign the PR to yourself and add appropriate labels. |
| 63 | +9. Add “**WIP**” label if the work is still in progress. |
| 64 | +10. Add "**DO NOT MERGE**" label if the work is not needed to be merged or there is no agreement on the work yet. |
| 65 | +11. Make sure to add Milestone to the PR to mention specific release. |
| 66 | +12. Request for review once the work is ready for getting reviewed |
| 67 | + |
| 68 | + |
| 69 | +## Creating an Isssue |
| 70 | +1. Make sure to add proper details to the Issue raised |
| 71 | +2. Upload screenshot(if possible) in dashboard issues |
| 72 | +3. Apply proper labels to the Issue |
| 73 | +4. Make sure to add Milestone and Project to the issue to mention specific release. |
| 74 | +5. Try to actively respond to the communication in case of comments in the same issue. |
| 75 | + |
| 76 | +## Reviewing a pull request |
| 77 | +1. Go to Files changed and check for the fixes proposed by the Pull Request |
| 78 | +2. Check for certain general criteria: |
| 79 | + a. The PR has no merge conflicts with the base branch |
| 80 | + b. The commits are squashed into one (if multiple) |
| 81 | + c. There is proper indentation and alignment |
| 82 | + d. No additional lines are added unnecessarily |
| 83 | + e. The code has proper explanation with the comment lines (If required) |
| 84 | + f. Do not merge the PR with "DO NOT MERGE" or "WIP" label. |
| 85 | +3. In case of the requirement of running the changes in the PR in local system follow the mentioned process: |
| 86 | + - To fetch a remote PR into your local repo, |
| 87 | + ``` |
| 88 | +git fetch origin pull/ID/head:BRANCHNAME |
| 89 | +where ID is the pull request id and BRANCHNAME is the name of the new branch that you want to create. Once you have created the branch, then simply |
| 90 | +git checkout BRANCHNAME |
| 91 | +``` |
| 92 | + -If modification is required, then either “Request for changes” or add “General comments” for your feedback |
| 93 | + |
| 94 | + - For more information about reviewing PR in github go through: |
| 95 | +https://help.github.com/en/articles/about-pull-request-reviews |
| 96 | +https://help.github.com/en/articles/reviewing-proposed-changes-in-a-pull-request |
| 97 | + |
| 98 | + |
| 99 | + |
0 commit comments