A Foolproof Method to Verify GitHub Contributions

on

 

Photo by Stephen Kraakmo on Unsplash

When using GitHub as a collaboration tool to maintain documentation, you can contribute to the documentation in GitHub via Pull Requests (PRs) by adding new content and making improvements to the existing content. In addition, you can also review PRs sent by other contributors. The rich diff mode in GitHub does not display the exact output that appears when you run MkDocs. Therefore, there is a high chance that you may miss certain formatting aspects at the time of reviewing the PR. Here is a workaround to make the PR reviewing process foolproof.

Generally, when the PR is not too large and I notice multiple aspects that need to be improved in it, I click on the Edit file menu option, copy the content in the file, paste the content in my local MkDocs setup, run the MkDocs server, and check the content locally. Thereafter, I copy the content of the updated MD file, replace the existing content in the PR with the new content, and commit my changes to the existing PR. However, I recommend the following workaround if the PR is large and has images as well.

Workround

Follow the instructions below to review the changes in the PR locally:

  1. Optionally, check the name of the upstream repository.
    You only need to do this if you are not sure of the name of your upstream repository. 
    git remote -v
  2. Create a branch that corresponds to the specific PR. Format:
    git fetch upstream pull/<PR-ID>/head:<branch-name>
     
    Example:
    git fetch upstream pull/3810/head:temp1
  3. Navigate to the branch that you created in the previous step. 
    Format:
    git checkout <branch-name>
    
Example:
git checkout temp1

  4. Review the content of the PR locally using a code editor such as Visual Studio Code.

  5. Make and save the changes locally. Format:

    git add <file-path-or-folder-path>
    git commit -m "<commit-message>"
    Example:
Let’s assume that you are updating some content related to the pages in the create-streaming-api folder.

    git add en/docs/design/create-api/create-streaming-api/
    git commit -m "Revamping the streaming API content"

  6. Send the changes to your remote GitHub repository.

    Format:

    git push <your-remote-branch> <local-branch-name>
    Example:
    git push Mariangela temp1

  7. Navigate to your remote GitHub repository.
You can type in the exact URL of your GitHub repository and navigate to it or follow the steps below.
    1. View your remote references.

      git remote -v
    2. Press Ctrl and click on your remote repository link.
    3. Select Open URL to access the link.

  8. Close the original contributor's PR.

  9. Create and send a new PR with the changes that you added. I would recommend that you add a link to the original contributor’s PR in your new PR.

Real Life Example

The following is an example of how I used the above steps to contribute to the WSO2 API Manager 4.0.0 documentation.
I reviewed the content in Pull Request (PR) [1] locally and then pushed my changes on top of the original contributor's changes via a new PR [2].



I genuinely hope that this blog post will be helpful to some of you who are using MkDocs together with GitHub. Drop a comment below on what you think of this workaround.


Acknowledgments

A huge thank you goes out to Prasanna Dangalla for introducing me to the above-mentioned workaround.

Comments

Post a Comment