# A Completed Pull Request Takeaway: + Virtual Environment + Branch Operation + Continuous Integration 1. Search how to download **git** as a command line tool in your computer. 2. Find the codebase url through the green button on our GitHub repository. 3. Use `git clone ` to clone the remote codebase into your local machine through the command line. No worry if your shell (command line) looks different from mine (The operations are same in the Mac and Windows systems). 4. Switch into **geochemistrypi** repository. Activate your virtual environment (**venv** or **conda**). In this case, I use conda to set up. It is a good habit to use a specific virtual environment for a specific Python project. Then, use `pip install -r requirements.txt` to download the dependencies. 5. Use `pre-commit install` to set up the git hook scripts, which will be used later on, no need to worry! You only need to run this command once in this local repository unless you clone another one again in other local directory. 6. Use **Visual Studio Code** (Recommended IDE) to open the codebase and don't forget to activate your virtual environment as the picture shows below. 7. Create a new git branch to develop on your own path. You can name the branch name as your identification or as the function you are going to build up. 8. Do some modifications on the codebase. For example, in this case, I update the badge information of READM.md. 9. After finishing modifications on the codebase, you need to use `git status` to check what file has been modified. 10. It is a good habit to use `git diff ` check whether the changed content on that specific files respectively is what you desire to make. After enter the command, the console will switch into **diff display**. In **diff displays** , press the keybord `j` to scroll down and press the keyboard `k` to scroll up. `+` refers to the line added while `-` refers to the line deleted. Press the keyboard `q` to exit from the **diff display** after checking. 11. Use `git add ` to staged the files for commit. 12. Use `git commit -m "tag: message"` to make a local commit. It is a good habit to follow up the principle that one commit for one functionality implementation or one optimization or one bug fix. It is allowed to push multiple commits to the remote codebase with one pull request. Please include the following tags in the beginning of your commit message to make more organized commits and PRs. It would tell exactly what use it is in this commit. + `feat`: a new feature is introduced with the changes + `fix`: a bug fix has occurred + `perf`: an existing feature improved + `docs`: changes to the documentation + `style`: code formatting + `refactor`: refactoring production code + `revert`: version revertion + `chore`: the change of developing tools or assisted tool + `test`: adding missing tests, refactoring tests + `build`: package the codebase + `ci`: continue integration + `BREAKING CHANGE`: a breaking API change 13. Continuous Integration (CI): In our codebase, we set up a pre-commit locally before. Normally, it will automatically check code grammar and correct code styles for your commited code. (1) In this **successful case**, it indicates that everything works well. No code grammar mistake and code style conforms to the configuration. Hence, no need to do further, you can push the local commit to remote codebase in the GitHub. (2) In another **failed case** (I did another experiment before, not in this docs!), it indicates that there are three files where import statements don't conform to the specification. Hence, it corrects them for you, which means that you don't need to manually correct them by yourself. The next step is to use `git status` and `git diff` to check the details in the corrected files to see what CI tool has done for you. You would see that you need to use `git add` again. Because CI tool has modified your code , you need to do a standard git commit process again. Again, you need to run `git commit` again. Just use the previous same command. Now, it passes! Fancy is it? Until now, you are allowed to push the local commit to remote codebase in the GitHub. 14. Back to the **successful case**. Now, it is time to push your local **dev/Sany** branch to the remote **dev/Sany** branch. It may not created yet, but no worried, it will be shown later. Firstly, use `git pull origin main --rebase`. This command pulls the latest changes from the remote **main** branch and applies them to your local **dev/Sany** branch, while also rebasing your local changes on top of the new changes from the remote. (1) **No conflict case**: In this example, it indicates that there is no conflict with the remote **main** branch. Quite normally, sometimes, when you are coding in your own branch, the remote **main** branch is far ahead of yours. It is likely that there are conflicts existing so you need to resolve the conflicts before merge your remote **dev/Sany** branch into remote **main** branch. The way through `git pull origin main --rebase` can save you troubles. If there are any conflicts between your local **dev/Sany** changes and the remote **main** branch's changes, Git will stop the rebase process and alert you that there are conflicts that need to be resolved. In this case, there is no conflict at all. If in your own case, there are some conflicts, to resolve the conflicts, you will need to edit the affected files manually on VSCode IDE to resolve the differences between the conflicting changes. Once you have made the necessary changes, you can stage the changes using `git add`, and then use `git rebase --continue` to continue the rebase process. Git will then apply your local changes on top of the new changes from the remote, incorporating the changes you made to resolve the conflicts. It's worth noting that resolving conflicts can sometimes be a complex process, especially when there are multiple conflicts across several files. If you're not familiar with resolving conflicts in Git, it's a good idea to read up on it first or seek help from experienced Git users (Sany or others) to avoid any unintended consequences. The picture below is the successful case without conflicts. After resolving all conflicts, you can then use `git push origin dev/Sany:dev/Sany` to push your local changes to the remote repository. This command pushes your local **dev/Sany** branch to the remote repository and creates a new remote **dev/Sany** branch if it does not exist yet. The colon (`:`) separates the local branch name from the remote branch name. （2）**Unstaged changes case**: In this example, it indicates that some files, which are modified and tracked by git, haven't been commited yet. Probably, these files are not the ones you want to push because they are under development. In Git's protection mechanism, when there is some tracked and modified files in your working directory, you are not allowed to pull and merge the remote branch **main** into your local branch. However, if your working directory only includes untracked files, this problem like the picture shown below wouldn' t happend. Fortunately, you can use `git stash push` to save those changed files into a hidden zone temporarily without committing them. Now, you can use `git pull origin main --rebase` and follow the same procedure as in the **no conflict case**. Once you finish pushing, you can use `git stash pop` to bring back the modified files into your working directory. For more information about **git stash** , plz google it. 15. Now, it is time to creat your first **PULL REQUEST**. Wowww, what a long journey! Copy the url with underline https://github.com/ZJUEarthData/geochemistrypi/pull/new/dev/Sany (it is different in your case, check your own information) and open it with a browser. You would the page directing you to create a **pull request** through clicking the green button. It is done!!! Then, no need to operate anymore . As a normal developer, you are not allowed to merge by yourself. Our maintainers will check and merge later on if it is good. The page below is only visible to our maintainers.