|
| 1 | +# Contribution to ParaPhraseGen |
| 2 | + |
| 3 | +It is essential that you know how to use Git as well as GitHub. While the maintainers will be more than happy helping you make your first PR, prerequisite know-how makes it easier for everyone involved. Check [this](https://github.com/firstcontributions/first-contributions) guide if you've never contributed to a project on GitHub before. |
| 4 | + |
| 5 | +## Contribution Workflow |
| 6 | + |
| 7 | +1. Fork the repo from GitHub |
| 8 | +2. Clone the fork locally |
| 9 | +3. Setup a remote to the upstream ( `git remote add upstream https://github.com/adeecc/ParaPhraseGen.git` ) |
| 10 | +4. Create a new branch for the feature you are working on ( `git checkout -b branch-name` ) |
| 11 | +5. Develop on `new-branch` |
| 12 | +6. Commit your changes to the `new-branch`. ( `git commit -am "Descriptive Commit Message"` ) |
| 13 | +7. Update local dev to match upstream's dev ( `git fetch upstream dev`) |
| 14 | +8. Merge with local dev ( ` git checkout dev; git merge upstream/dev` ) |
| 15 | +9. Rebase `new-branch` ( `git checkout new-branch; git rebase dev`) |
| 16 | +10. Push your branch to GitHub ( `git push origin new-branch` ) |
| 17 | +11. Go to GitHub and submit a Pull Request to dev branch |
| 18 | + |
| 19 | +## Pull Request Guidelines |
| 20 | + |
| 21 | +1. Try to limit the number of commits per PR to 1. If the changes are diverse enough to be put in 2 different commits, consider submitting 2 different PRs instead. (If there is no option but to submit multi commit PR's, please talk to the maintainers beforehand and read the section on multi commit PR's) |
| 22 | +2. When submitting a PR, follow the PR template and make sure to complete all the steps in the PR checklist in the PR template. (You will be able to see the template when you are submitting a new PR). |
| 23 | +3. 4 automated checks are run whenever a PR is submitted. Make sure Your PR can pass all of these checks. (Read further for details) |
| 24 | +4. Code Style Checks - 2 code style checks run for every PR, using ESLint and Prettier. It is considered good practice to run these tools locally and ensure your code meets our style guidelines before submitting a PR |
| 25 | +5. Unit Test Checks - Unit Tests are run for every submitted PR. This test also checks for code coverage. Any PR, irrespective of how important it is, will be rejected if it fails to meet the required 75% code coverage thershold |
| 26 | +6. Build Checks - The application is build and a smoke test is conducted to see if the application responds for every submitted PR. |
| 27 | + |
| 28 | +## Multi-Commit PRs |
| 29 | + |
| 30 | +**Note**: This section has concepts that may be too advanced for new Git users. It is recommended that such contributors |
| 31 | +ask for help from those more experienced. |
| 32 | + |
| 33 | +Sometimes a PR will require or endup with more than one commit. There are two possibilities of this happening: |
| 34 | + |
| 35 | +- Additional granularity that each commit provides to a feature branch. An example of this is when you make big |
| 36 | + changes to the UI to follow a new set of guidelines or standard. In such a case, it may be beneficial to have separate |
| 37 | + commits for each fragment/activity that is changed. |
| 38 | + |
| 39 | +- New commits pushed after a review from the maintainer(s). New commits are recommended over amending existing commit(s) |
| 40 | + and force pushing since the latter would make your changes a lot harder to review. |
| 41 | + |
| 42 | +Note that in both cases, only a single PR is required. It is the PR that will have multiple commits. In both cases, our |
| 43 | +concern is the additional commits that are added to a PR to fix problems found during code review. |
| 44 | + |
| 45 | +Consider the case of a PR with two commits, `A` and `B`. After a code review, let two additional commits `C` and `D` be |
| 46 | +created to fix problems found in `A` and `B` respectively. It might be beneficial to have both `A` and `B` as individual |
| 47 | +commits after merging them into `development`, instead of squashing all of them into a single commit. However, a simple |
| 48 | +rebase of the PR would include `A`, `B`, `C`, and `D` in `development`. This reduces the readability of the `development` |
| 49 | +branch's history. |
| 50 | + |
| 51 | +A possibility would be to makes the necessary changes, stage them, and then do `git commit --amend` to amend `B`. We can |
| 52 | +then force push the changes. However, this is not ideal for two reasons: `B` now has changes that were supposed to fix |
| 53 | +`A`, and we force pushed. |
| 54 | + |
| 55 | +Ideally, we would like to squash `C` and `D` into `A` and `B` respectively. This can be accomplished by doing an |
| 56 | +interactive rebase using `git rebase -i HEAD~4`, reordering the commits in the todo list, and then squashing them |
| 57 | +together. However, this process is tedious. |
| 58 | + |
| 59 | +Git allows us to automatically squash or fixup such commits. Git does this by editing the todo list for us when we |
| 60 | +perform an interactive rebase. Assume we want to automatically squash `C` into `A`, and `D` into `B`. This can be |
| 61 | +accomplished as follows: |
| 62 | + |
| 63 | +1. Stage the changes to be committed. These changes will form commit `C`. |
| 64 | +2. Perform `git commit --fixup ...`. Here `...` is either the commit hash, or commit subject of `A`. This will create |
| 65 | + commit `C` with the subject as `!fixup ...`. This annotation tells Git which commit `C` will _fixup_. |
| 66 | +3. Repeat the above steps to create `D`. |
| 67 | +4. Perform `git rebase -i --autosquash HEAD~4`. Use the annotations in the commit subjects, Git will generate a todo list |
| 68 | + such that `C` and `D` will fixup `A` and `B` respectively. |
| 69 | +5. Continue with the rebase and fix any merge problems you encounter. |
| 70 | + |
| 71 | +Note that `fixup` can be replaced with `squash` in the above steps as well. However, the option `--autosquash` for |
| 72 | +`git rebase` will remain the same for both cases. |
| 73 | + |
| 74 | +For the sake of completeness, the difference between fixup and squash is as follows: |
| 75 | + |
| 76 | +> When `C` fixes up `A`, the changes of `C` is applied to `A` and the commit message of `C` is discarded and only that of |
| 77 | +> `A` is used in the new commit. |
| 78 | +
|
| 79 | +> When `C` is squashed with `A`, the changes of `C` is applied to `A` and the user is prompted to provide a new commit |
| 80 | +> message for the squashed commit. |
| 81 | +
|
| 82 | +For further reading, [here][auto-squash-doc] is the documentation for `--autosquash`. |
| 83 | + |
| 84 | +[auto-squash-doc]: https://git-scm.com/docs/git-rebase#Documentation/git-rebase.txt---autosquash |
0 commit comments