How to submit a PR (Pull Request)

Getting your Trinity Audio player ready...

If you’re familiar with Git principles and have committed code on Gitee, you can basically ignore this section, but there are two important things to note:

  • Before you submit code to the OpenHarmony community, be sure to sign the DCO
  • Any local commit must be signed, and git commit must carry the -s parameter

FUNDAMENTALS OF GAT

Regarding the history and principles of git, the author has found a good introduction to the article, you can refer to 

Living In Harmony is a reader-supported publication. To receive new posts and support my work, consider becoming a free or paid subscriber.

Subscribed

https://zhuanlan.zhihu.com/p/66506485

 For beginners, I personally think it is more appropriate to use the following diagram to understand. 

  1. fork: refers to copying a copy from the official website repository to your own account repository, and the content of the two is the same at this time node;
  2. clone: refers to downloading from your own account repository to the local client;
  3. commit: refers to the cloned code, modify and correct some content as needed, add new content, delete redundant content, and form a record.
  4. push: refers to submitting your own changes to your account repository;
  5. PR: refers to submitting your own changes from your own account repository to the official account repository;
  6. merge: refers to the commiter of the official account repository who accepts your changes;
  7. fetch: Pulls the content of the official account repository to the local computer.

A few questions:

  • Can I clone directly from the official account repository? Of course you can, but generally speaking, it is difficult for us to directly obtain the permission to push to the official account, so it is recommended to fork first and then clone from your own account repository.
  • How do I keep my account repository in sync with my official account repository? You can directly use the synchronization function on the web page, and the other is to first fetch from the official repository on the schematic diagram, and then push it to your account repository.
  • Clone and fork are required every time? A fork can be understood as an initial copy on the server side, which only needs to be done once, and a clone is an initial copy from the server to the local server, which only needs to be done once.

PR hands-on

Basic tools and configuration environment

GIT TOOLS

It is recommended that you use command-line tools in the Windows environment, if you are MACOS or Linux, I believe it will be easier for you to use. You can download the git bash tool from the git bash download address and install it. Once installed, right-click on your working directory and git bash will appear.

After clicking on Git Bash, you will be taken to a Linux terminal interface, which is where we will upload the changes from the local to the local one

The main battleground for personal repositories on Gitee.

Some basic Linux commands (cd: switch directory; cat: refer to files, etc.) can be used in this interface, and you can use the help + command to see how to use the specific commands. Keep in mind that you can type the first few characters of the command and then use the tab key to complete it, after all, everyone’s memory is not very good.

Supplemental SSH public key

Using an SSH public key allows you to use a secure connection when communicating with Gitee on your computer. So how do we get the SSH public key of our PC? Right-click on the desktop and open git bash

Enter ssh-keygen.exe and press Enter, press Enter again, then type y, and press Enter two more times to generate your own SSH public key holding file.

git can’t directly ctrl+c/v to copy and paste, but you can select the ssh public key to keep the file (i.e., Your public key has been saved in) and then right-click Copy to copy, Paste to achieve this function.

Use the cat command to view the generated id_rsa.pub file, and enter cat (right-click Paste and paste the ssh public key to hold the file) Enter to view the specific information.

 Start with ssh-rsa, select the whole paragraph and then copy, open the gitee official website, find the ssh public key in the settings, paste it to add the public key to our gitee account.  

Configure the submission information

When we submit changes to the Gitee repository, we need to inform everyone who initiated the committed, otherwise how will you know which heroes contributed to the open source community. So in order to avoid having to re-enter some commit information (personal account information) every time, we need to use git bash to configure the commit information in a unified manner.

First of all, remember your personal space address, which can be seen on the web link on your personal homepage.

Open git bash, enter the following commands in turn and press enter, the first two commands do not respond, which proves that the configuration is successful.

git config --global user.name "xxxx"   (配置用户名,xxxx为账号用户名,即个人空间地址)
git config --global user.email "xxxxxx@xxx"      
git config --list         (查看配置情况)

Congratulations, you’ve successfully completed your preparation to contribute to the open source community!

Install the code as well as the document editing IDE

If you don’t have a familiar tool, I personally recommend using the OpenHarmony southbound device IDE DevEcoTool as our C/C++/Markdown document editing tool, otherwise you can’t open many MD documents (programmers’ favorites). IDE download address: Download the corresponding version and install it according to the installation guide. 

This is an IDE for Visual Studio Code, you can install a lot of VS plug-ins, for example, we modify the commonly used Markdown in the document.Open the IDE tool,Search for Markdown in the extension plug-in,Install Markdown All in one/Markdown preview enchance/Markdown PDF several plug-ins。

Let’s get into the action and get into the PR conversation journey

Goal: The students of the knowledge system joint operation group and the infrastructure group held a live broadcast of the knowledge empowerment course, and the live broadcast event had an after-class check-in link, so let’s put forward a PR to do a check-in action.

Fork the official repository

Synchronize the contents of the official repository to your own personal repository

The official address of the active repository 

After forking, we can see the repository in our Gitee account.

Clone repository content to the local computer

Open the repository under your personal account, enter the clone interface, and copy the link address of clone.

Use the git clone command under the gitbash tool to complete the clone operation. –depth=1 means that only the latest version of the current repository is clone, so as to avoid too much clone time due to the large repository history.

git clone https://gitee.com/Cruise2022/online_event.git --depth=1

After the clone is complete, you can see the clone repository in the local directory. To note that the location of the local directory is determined by the location of git bash, for example, if you start git bash on the desktop, the clone repository will appear on the desktop.

Edit the local file

Open the six-phase growth punch-in job in the local directory, create a new punch-in job folder (it is recommended to use your own gitee personal space address to name your punch-in job folder to avoid conflicts), copy the readme.md documents to your punch-in job folder, you can use the IDE you just installed to edit the md file, or you can use other markdown tools to edit the md file (e.g. Typora) 

Commit the modification to the local repository

readme.md the modifications are finished and saved, then start using the git command to view and commit. In this case, you need to do git bash in the local repository location, otherwise git will not find the modified content. The main steps for submission are as follows:

  1. To view the modified file, run the following command:
git  status

 2. Add the modified files to the temporary storage area and enter the following command to operate

git  add *

 3. Submit the modified file to the local warehouse and sign it, and enter the following operation command. -s is a signature indicating that you are the submitter this time, and -m is a note on this submission behavior to explain to everyone what you submitted and modified.

git commit -s -m  "add:Knowledge System Empowerment Course Sign-in"

 4. Finally, let’s check it with git status, and we can see that there are no more changes. 

Push new content from the local repository to the account repository

  1. After the local change is committed, the change will be saved to the local repository and a LOG will be formed. LOG means to commit records, and all operations in this repository will be stored as a LOG, so that you can easily roll back and modify them. Use the git log command to view our commit history. (You can’t enter other commands after entering the git log command, and you can exit by pressing Ctrl+C at the same time.) )
git log

 2. Now we need to push the changes from the local repository to the personal repository on Gitee, and use the git push command to do this.

git push origin master

 3. Going to our account, we look at the repository and see that it has changed.

Submit a PR from your personal account repository to your official repository

Go to the repository in your personal account and click Add PR to start submitting PR. Once submitted, you can see the PR we submitted. 

Is it over at this point? We need to add a comment under this PR before the gate control starts to check (the gate control refers to a series of compliance checks set by the administrator to check whether the code is compliant, whether the quality is qualified, and whether the DCO agreement is signed). Then we can see that various compliance checks of CI have begun, make a cup of coffee, sit back and wait for the inspection to pass, and then the administrator of the warehouse will merge (PS: some commits will be rejected by the administrator for various reasons, pay attention to the administrator’s reply and modify and resubmit in time)

So far, congratulations on successfully sending your first shout to the OpenHarmony open source community!

Although this is only a small step, we believe that this will be a big step forward for the community, and we look forward to you joining us and contributing to open source!

FAQ

  • I have registered gitee before, this time I used a new account, but the push failed The phenomenon is as follows: The specific reason is that our windows SSH credentials may still maintain the previous settings, and we need to manually change the credential bar**git:https://gitee.com**.  
  • After installing the markdown-related plug-ins of visual studio code, there is no preview function Check whether visual studio code is in Restricted Mode mode, look at the lower left corner of the IDE interface, if so, click Close. Right-click on the markdown interface to display the preview feature. 

homework