How to Contribute to Open Source Project - Your First GitHub PR

Contribute to Bytebase's Open-sourced Documentation

4 min read

If you are a tech beginner / non-tech person and wonder how to contribute to an open-source project, this is THE article for you. I'll take Bytebase's open-sourced documentation as an example to guide you through the whole process.

Bytebase is an open-source database tool for DBAs and developers; it's the GitLab for database schema lifecycle management. It open-sourced its official documentation since v1.0.2.

Let's get started; make sure you install Git and have a GitHub account. If you have any questions about git, ask google or git-scm.com/docs.

Preparation

  • Visit github.com/bytebase/bytebase.com; as we can see, actually Bytebase open-sourced the whole website, but we only pay attention to docs/. image.png

  • Under your project folder, do git clone to download the whole repository. image.png

  • Yes, now we have the code, and here is the most popular editor code.visualstudio.com

image.png

  • Open the folder from VSCode

image.png

Delete a file

Do the Delete

  • Our first example is to remove a page - Bytebase sunset a feature in v1.0.0, but the related file is still there. image.png

  • Within the editor, it's super straightforward - delete this file. image.png

image.png

Commit and Push

  • After deletion, we use Terminal to view the current status - the file is deleted, yes, that's right!

image.png

  • Git commit with the message telling what this commit is for.

image.png

  • The changes are committed, and that's not enough; we need to synchronize it to the remote branch so that others can see. And ... We encountered this!

image.png

  • It's because we are now in the main branch. If we build our own code repository, it's OK to push directly to the main branch. But now we are trying to make changes to others' project. Let's get to the document guidance here. bytebase.com/docs/document-write-guide

image.png

Create a PR

  • "Create a new PR" - how? First, we need to create a new branch to push our local copy to remote. If you are similar to me - not so familiar with the git command, google is always there for you.

image.png

image.png

  • We use the command "git checkout -b xxx" to create our branch

image.png

  • Then push to remote

image.png

  • Set the upstream and push to remote "git push --set-upstream origin remove-sql-rollback-page".

image.png

  • Let's get back to GitHub; click the "Pull requests" tab

image.png

  • We can see the push, but let's click "New pull request"

image.png

  • Here we can see our branch, click!

image.png

Here, you can make the comparison, but it's pure deletion for our case. Click "Create pull request"!

image.png

  • Succeed!

Update a file

Do the Update

  • Our second case is to update. When we copy images from google docs, it will have its self-generated link. What we need to do is to replace that with static/doc-assets/xxxx.png from the same repository.

image.png

image.png

  • Firstly, I download all the related images and move these to static/docs-assets/

image.png

  • The file names should be prefixed to stay together image.png
  • Then update the corresponding file. I keep the old files there to ensure the new images look the same.

image.png

image.png

image.png

  • Do git status to view the status.

image.png

Preview Locally

image.png

  • We run "pnpm i & pnpm dev" and it compiles successfully. Now we can visit localhost:3000 and preview the whole site.

image.png

image.png

image.png

New PR

  • Everything seems fine to me, now let's create another branch and then a new PR

image.png

image.png

image.png

Change Requests

  • Then, I got my first "change request".

image.png

  • Then, the second.

image.png

  • Yes! I forgot to push all the images ... Add and another commit and push.

image.png

  • Remove the letters "dddd".

image.png

  • Then, I need to re-request reviews from them again.

image.png

LGTM and Merge

image.png

  • And I can merge!!!!

image.png