Skip to content

Contributing to BBCodePlus

Jump to bottom
bkraul edited this page Mar 20, 2019 · 9 revisions

It seems this plugin is more widely used now than it was during its humble origins. More people are beginning to collaborate with us in enhancing the plugin.

However this presents a challenge when managing and applying pull requests. The following is a guide on forking, developing, and ultimately issuing pull requests the BBCodePlus repository.

WARNING: NEVER make changes or commits to your fork's local master branches. Doing so will break the synchronization with upstream. It should only be synchronized by pulling from upstream master; (i.e. to synchronize your master, you would use: git pull upstream master on top of your local master branch). Consequently, please do not issue pull requests from your fork's master to the upstream master.

The current masters for BBCode are:

Branch Description
master Support for MantisBT 2.x (current production version).
master-1.3.x Support for MantisBT 1.3.x (legacy).

Forking the main project

You can fork the main organizational project by going to https://github.com/mantisbt-plugins/BBCodePlus and pressing the Fork button on the top right.

Graphical representation of Git flow

Git flow

Setting origin and upstream remotes

The origin remote should be automatically set during the cloning of the forked repository. You can check it by executing the following on Git Bash:

git remote -v

It should yield something like:

origin  git@github.com:[USER]/BBCodePlus.git (fetch)
origin  git@github.com:[USER]/BBCodePlus.git (push)

If the origin remote is not set, you can set it by executing:

git remote add origin git@github.com:[USER]/BBCodePlus.git

Then make sure that your local master branch is set to track the desired master at the origin (i.e. master):

git branch -u origin/master

Now we need to set up our upstream, which is where our official project updates will be coming from. Execute the following in the master branch of your local clone.

git remote add upstream "https://github.com/mantisbt-plugins/BBCodePlus.git"

Then check that you now have origin and upstream remotes

git remote -v

It should return something like this:

origin    git@github.com:[USER]/BBCodePlus.git (fetch)
origin    git@github.com:[USER]/BBCodePlus.git (push)
upstream  https://github.com/mantisbt-plugins/BBCodePlus.git (fetch)
upstream  https://github.com/mantisbt-plugins/BBCodePlus.git (push)

Syncing your fork's master to upstream.

This is something you need to do often, preferably before starting work in a new feature branch. First we need to fetch the upstream changes into our current local master.

First, we need to make sure we are in our local master branch (i.e. master):

git checkout master

We can now pull the changes from upstream into our local master:

git pull upstream master

After pulling the latest upstream into master, make sure to push the latest changes back up to your fork like so:

git push origin master

At this point we can create a development branch or a feature branch with the latest official changes. You can also apply the same changes into an existing develop/feat branch by executing:

git checkout develop # or any other feature branch name
git pull origin master

However, you must always make sure your master has been synced to the upstream/master first. Also, there is a chance of more conflicts when merging a master branch into a feature branch because of changes already made to the branch. Conflict resolving may have to be done. There should seldom be any need to sync a development branch on top of a master.

Creating pull requests

After completing your changes in your development branch, you can then push such changes to your fork. Once those changes are pushed, you can create a pull request. A pull request sends your feature changes to the main project for approval by the code reviewer. You do this by accessing the GitHub web interface, and clicking New Pull Request while in your fork's branch of choice.

Make sure the pull request information set as follows:

  • base repository: mantisbt-plugins/BBCodePlus
  • base: [ your desired master, i.e. master]
  • head repository: [USER]/BBCodePlus
  • compare: [ your feature branch, i.e. develop, feat-myfeature ]

After this, the project's maintainers will process your pull request, either accepting it which will merge it into the main project, temporarily rejecting it, or closing it. If your PR is rejected due to incompatibility, you may be given a chance to correct and recommit to the same branch, this updating your PR, until compliant.

Cleaning up and repeating the process

Once your pull request has been accepted and merged into any of the main project's masters, you will need to repeat the process of syncing your project with upstream/master. (See above).

It is also recommended to delete your feature branches once you are fully done with the feature so as to avoid clutter, but since it is your fork, that is up to you. You can leave development branches (i.e. develop) active, as long as you keep them updated with the latest changes from master. Only remember that branching can get really complicated, really fast. Keep it simple.

Now, what was that number one rule?

PLEASE NEVER COMMIT DIRECTLY TO ANY OF YOUR FORK'S MASTERS OR ISSUE PULL REQUESTS FROM THEM 😡😅

Clone this wiki locally