Notifying Changes to Debrief

Now we will look at notifying changes to Debrief. As we've mentioned already, Debrief has been under continuous maintenance for 20-years now and, as you can imagine, has evolved considerably over that time. As it is open source and hosted on GitHub, anyone can take a copy of the main repository - or what is termed the ‘main branch’ - at any time, and then work on it on their computer. When this happens, this copy [of the main branch] is called a ‘fork’.

Later, after modifications have been made to the fork, the developer can request that other users discuss, review, or comment on these changes. If the changes are acceptable and will benefit the program, they can then be pushed to into the main branch.

How this works

For example, if there is a bug in the software and you've just raised a new issue. The developer assigned to this issue will then take a fork from the version of Debrief that you've reported in your issue (using the structure that was advised in the post How to Create a Debrief Issue), install the same java version as you have on your system, and then try and recreate the issue.

When the issue is resolved, the developer then needs to notify interested parties that the code needs to be reviewed. This actual notification is called a Pull Request - it’s a broadcast to notify other interested parties that a change has been made to the code and, in the first instance, to invite them to review it.

From a user’s point of view, it is interesting to observe these requests as it’s an indication of new features in Debrief.

Viewing a Pull Request

Any logged-in user can view a pull request. Click on the subject of the request and you will see its details:

This particular request is now closed, but you can clearly see the numbered items on the image:

1. The reason for the pull request
2. The 9 additional commits this request has: each of these can be clicked on to drill-down and view the code
3. The total number of lines of code modified in this change.

Who Can Initiate a Pull Request?

Though any registered and logged-in GitHub user can initiate a Pull Request, this section is geared primarily towards Debrief developers or advanced Debrief users who have implemented changes to their ‘fork’ and wish to have them included in the main application, it isn’t for normal users. The only requirement is that changes have been made to the fork (as we’ll show below).

How to Initiate a Pull Request

To initiate a new Pull Request, in the Debrief Repository:

1. Click on the Pull Requests tab and then click on the New pull request button:

Note: in the top right of the image, you can see that there are 9 forks from the main repository.

2. The screen will refresh and you will see the following:

As you can see, the Create pull request button is disabled. This is because there haven’t been any changes between the base repository and the fork it’s being compared with.

3. However, clicking on the Compare drop-down and selecting a fork that has changed will enable you to Open a pull request:

4. Once you’ve entered your comment, click on the Create Pull Request button. The screen will refresh and your request will become an open pull request:

That’s the basics to pull requests and their function. As mentioned, they’re a very useful GitHub tool which enables you to keep track of what’s going on as well as to keep abreast of all changes to Debrief regardless of whether you’re an interested party, a user, or an active contributor.