Recently, I was fortunate to participate in the open source community activities, and practiced the document development of GitHub + MarkDown through the Apache Pulsar project. In the process of communicating with children in the open source community, I learned that tcers who are not technical professionals are often dissuaded by seemingly complicated tools and processes, even though they are enthusiastic about community contribution. So here, BASED on my personal practice and experience, I will share my “simplest” operation instructions.

In this article, it will be introduced in the following order:

  1. Overall process and difficulties description: Overview of the overall process, and point out the operation difficulties.
  2. Knowledge and preparation: The basics and preparation needed to deploy and use GitHub + MarkDown for document development.
  3. Description of operation interfaces: Describes the operation interfaces involved in the whole process.
  4. Working environment deployment instructions: Deploy the local PC as a terminal for participating in open source projects. Typically, the working environment only needs to be deployed once during the life of the project; If the working environment is damaged, delete the local file and redeploy it.
  5. Description of daily workflow: When the working environment has been deployed, the daily workflow needs to be fully executed for each round of modification to achieve closed loop.

I. Description of the overall process and difficulties
>> Overall process

  • Solid line: operation procedure and data direction.
  • Serial number: Procedure.
  • Above the dotted line: GitHub Cloud operation.
  • Below the dotted line: Local operation.
  • Dotted line cutting: online/offline transmission operation.
  1. Fork: Create a backup copy of the apache/pulsar directory as a personal

    /pulsar directory. Subsequent changes to the Pin PulSAR project were implemented based on the personal directory.
  2. Clone: Copy the project files in the personal

    /pulsar directory to the local directory.
  3. Fetch upstream: Set up synchronization updates between local files and Apache/Pulsar to ensure subsequent modifications are made using the latest version files.
  4. Branch: Creates and modifies branches.
  5. Edit: Use the editing tool to modify the content of a file.
  6. Commit: After the file is modified, the file is committed.
  7. Push: Upload files to personal

    /pulsar directory.
  8. Pull Request: submit the PR change to Apache/Pulsar, and log in to Apache/Pulsar after confirmation.

>> Difficult points

  1. The deployment of the working environment involves many command line operations, which may not be particularly friendly to non-technical users. If possible, you can ask technical partners to help complete the deployment. However, if you try to complete it independently, you will get a great sense of achievement. I believe you can do it.
  2. In daily work, special attention should be paid to file versioning to avoid confusion when submitting pull requests. For details, see Routine Workflow Description > 1. Branch

Two, prepare knowledge and preparation work

  • How to bring up the command line dialog box.
  • How to use the DOS command to locate a specified directory. Related commands include: CD, CD.. , CD \, < drive >, CD < directory >,dir

3. Operation interface description

  • GitHub Web page: Used for GitHub cloud operations. For example, fork and pull Request.
  • Cli: Recommended for deployment in the working environment.
  • GitHub Desktop: Recommended for daily workflow.



Description of working environment deployment

  1. Fork: Create a backup copy of the apache/pulsar directory as a personal

    /pulsar directory. Subsequent changes for pulSAR projects were implemented based on the personal directory.
  2. Clone: Copy the project files in the personal

    /pulsar directory to the local directory.
  3. Fetch upstream: Set up synchronization updates between local files and Apache/Pulsar to ensure subsequent modifications are made using the latest version files.


1. fork


2. clone



3. fetch upstream

git remote -vCopy the code
origin    https://github.com/$user/pulsar.git (fetch)origin    https://github.com/$user/pulsar.git (push)upstream  https://github.com/apache/pulsar (fetch)upstream  https://github.com/apache/pulsar (push)Copy the code
git checkout mastergit fetch upstreamgit rebase upstream/mastergit push origin masterCopy the code

5. Daily work process description

  1. Branch: Creates and modifies branches. Note: 1) An issue corresponds to a branch. 2) Each change must create a change branch, do not directly modify on the master branch.
  2. Edit: Use the editing tool to modify the content of a file.
  3. Commit: After the file is modified, the file is committed. Note: Make sure to commit to the correct change branch when submitting the file.
  4. Push: Upload files to personal

    /pulsar directory.
  5. Pull Request: submit the PR change to Apache/Pulsar, and log in to Apache/Pulsar after confirmation.


1. branch

  1. Set Current Repository to

    /pulsar;
  2. Click Current Branch > New Branch to open the Create a Branch dialog box.




2. edit

3. commit

4. push

5. pull request


Six, summarized