Go With the GitFlow: A Layman's Guide for Submitting a Pull Request to the OpenBB Repository

We are grateful to anyone spending their time, energy, and efforts improving this open source project. There are thousands, if not millions, to choose from, so it truly is an honor to be selected from the pack. When we say, "no contribution is too small", we really mean it. It could be as small as a changing one letter in the documentation, correcting a typo. All of the little details add up to be a better product and a better user experience and we want anyone to be able to contribute.

By the end of this post, any level of contributor will be armed with the information required to successfully submit a pull request to the OpenBB code repository. The only thing required to get started is a free GitHub account.

When visiting the OpenBB repo in a browser, you will likely find yourself on the main branch.

The main branch is considered stable, which means that its current status does not necessarily reflect the state of development. Time is precious, so to avoid wasting it resolving an already addressed issue, check the open Pull requests first. Take a quick look there, and also peruse the open Issues to find any reports of similar problems to the one at hand. If there is an open Issue and it is unassigned, then it would be fair to assume that it is not actively being worked on. Add a comment requesting to be assigned to it, and then reference that Issue number in the Pull request when it is created. The Issue number is linked by including the # with the number, more on that later.

Before creating a new Pull request, it is important to switch to the develop branch. The flow of Pull requests goes from the develop branch into main. PRs opened on the main branch will not be accepted. The develop branch is located here, or from the main branch, as shown above, click on the drop-down arrow beside main.

For example's sake, we'll walk through a scenario using only a browser and the GitHub website. The problem we are addressing is within one of the introduction guides for the OpenBB Terminal. The specific issue is purely cosmetic, the title of the page does not reflect the contents. The section titled, Settings & API Keys, is a page dedicated entirely to API keys and does not touch on the settings menu. This title could be clarified by changing it to be, API Keys.

Now that we are on the develop branch, let's find the file to change.

https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/website/content/terminal/usage/guides/api-keys.md

Login to GitHub to edit a file directly on the website, and click the edit button located on the right side of the screen.

This will open the file in the online editor, and the screen should now resemble the capture below.

The thing we are looking to change is right at the top, line two, and we are going to update it to be:

title: API Keys

With it updated, click the commit changes button. This will pop-up a window for adding the commit message and naming the branch for this new patch.

The Naming Convention for Branches

As it says, you cannot commit to a protected branch, and a new branch must be created to start a Pull request.

Do not click on "Propose Changes" without strictly adhering to these conventions.

• Edit the Commit Message to describe the change being proposed.

  • "Updates api-keys.md title to be, 'API Keys'."

• DO NOT use the default branch name, change it according to these guidelines:

  • Bug, error, and typo patches are named: hotfix/{descriptive_name}
  • New or enhanced functionalities are named: feature/{descriptive_name}

If you do not follow these conventions, your Pull request will not be merged.

Our working example falls under the hotfix category, so let's update the fields appropriately.

With all our ducks in a row, we are now ready to propose the changes. Clicking on the green button will create the new branch and open a new Pull request.

If our patch was code-related, this is where we would describe in detail what the proposed changes are, which open issues it resolves, and what steps a maintainer should follow to test them.

Link any issues that the patch will resolve with the method outlined below:

Linking a Pull Request to an Issue Using a Keyword

Excerpt from: Linking a Pull Request to an Issue

You can link a pull request to an issue by using a supported keyword in the pull request's description or in a commit message. The pull request must be on the default branch.

• close
• closes
• closed
• fix
• fixes
• fixed
• resolve
• resolves
• resolved

If you use a keyword to reference a pull request comment in another pull request, the pull requests will be linked. Merging the referencing pull request also closes the referenced pull request. The syntax for closing keywords depends on whether the issue is in the same repository as the pull request.

To unlink an issue that you linked using a keyword, you must edit the pull request description to remove the keyword.

Include as much detail as possible by describing any changes to the behaviours and expected inputs/outputs of any function being touched by code changes. Read the template and check all boxes that apply.

Because our example is simply correcting a documentation page, most of the checklist will not apply. However, if any file names are changed, you must ensure that any links pointing to the old names are updated to reflect the new ones. In most cases, it should not be necessary to rename a file.

Open a New Pull Request

Make sure to do these steps when opening a new Pull request:

• Add all required details to the Pull request message body.
• Add labels.
• Tag any open issues the PR will resolve on merge.
• Ensure that the PR is being merged to the develop branch.

Add a label from the side bar:

If the Pull request being created is not quite complete, but is ready to begin the feedback process, open it as a Draft and mark it as "Ready for Review" when it is. A maintainer will review and either approve it or request changes.

Double-check that the Pull request is being merged from the named branch into the, base: develop branch.

When it's ready, submit it!

This creates the Pull request and triggers a series of automated tests which check for spelling mistakes, code linting and formatting, labels, as well as looks for changes in expected outputs. The testing suite is mostly focused on the code base, but regardless, check back in a few minutes to verify that it is passing. Green is good!

If you are having trouble with this part, leave a comment on Pull request saying that you are looking for help. This post was written with the beginner-novice in mind, a non-technical contributor. Developers contributing code should review the Contributing Guidelines for a comprehensive explanation of the testing suite and formatting guidelines.

For questions and additional community resources, join the OpenBB Discord server. On behalf of the entire OpenBB Team, thank you for participating in our community.