How to make a Pull Request

Members are encouraged to contribute software to DTVKit. Software can be a bug fix or a feature. DTVKit uses git for Configuration Management, with the git repositories held on GitHub. GitHub applies changes via Pull Requests.

This document describes the DTVKit process associated with the submission of a Pull Request to a DTVKit repository on GitHub.

DTVKit welcomes bug reports and feature requests, but there is no commitment by DTVKit to fix the bug or implement the feature request. The expectation is that the originator will resolve the issue and eventually submit a Pull Request, otherwise nothing will be done until and unless the necessary work is authorised by DTVKit management. Submitting a Pull Request should only happen when the bug fix or feature has been implemented and tested by the submitter.

The DTVKit preferred way of working is that a member who raises a bug report should also submit a ‘fix’ using a pull request with:

• Code that conforms to the DTVKit coding standard.
• Code that has been tested.
• Code that is accompanied by a test stream where appropriate.

Related links:

https://www.dtvkit.org/wiki/doku.php?id=coding_standards

https://www.dtvkit.org/wiki/doku.php?id=testing

Members are encouraged to submit new features in a similar fashion to a bug fix. If a member is looking for new features to be provided outside of the published DTVKit Roadmap, then a request can be raised via the DTVKit forum to see if there are any parties interested in providing the feature, or a request made to DTVKit management for its consideration.

Note: DTVKit management insists that if a member is wanting DTVKit to fix a problem then it should make a request to DTVKit. Outstanding bug reports will be reviewed, prioritised, allocated and costed in meetings held once a quarter. Bug fixing will then be performed subject to priority, engineering availability, and the available budget.

DTVKit does not accept patches unless authorised by DTVKit management, in which case the patch will be turned into a pull request. If it is necessary to submit a patch, the fewer files affected by the patch, the better. Furthermore, just as with Pull Requests we insist that bug fixes and features are submitted individually (“One bug fix or feature per patch”) and separately (“Do not mix bug fixes with features in a patch”)

DTVKit can be built in either 32-bit or 64-bit. We recommend using a 64-bit desktop build but 32-bit can be achieved via a VM. Depending on your circumstances, this may determine your decision as to whether you build for 32-bit or 64-bit. Some known disadvantages of using a 32-bit VM:

• System Administration of the Guest is frequently required.
• Video and Audio performance is impacted by the VM

The primary reason for running the App as a 64 bit executable on a 64 bit Host is that it keeps things simple. The disadvantages of the VM no longer apply, but the unacceptable disadvantage is that of testing on a 64 bit architecture when the target STB or TV has a 32 bit architecture.

The process is initiated by the submission of a Mantis ticket to DTVKit marked as New by the submitter. You should have received your credentials for Mantis when your company registered as a DTVKit member. If you do not have access, please contact info@dtvkit.org.

Link to Mantis: http://bugs.dtvkit.org/

Once you are within the correct project, select Report Issue in the task bar at the top of the page.

From here you can enter the issue details into the bug report. Please explain the issue with as much detail as possible. Explicit steps on how to reproduce the issue are highly recommended. If the bug report is fully detailed with information, it will most likely be moderated sooner.

When the ticket is created, the status will automatically be New. If the user intends to provide the pull request to resolve the issue, then they should change the status to Allocated.

DTVKit insists that bug fixes and features are submitted individually (“One bug fix or feature per Mantis ticket”) and separately (“Do not mix bug fixes with features in a Mantis ticket”).

Once the mantis ticket has been submitted, the user must take note of the given number (e.g. 971). This number will be required to create the git branch name (i.e. mantis-xxx) for the pull request. See below image for an example of the named pull request in Github:

Please note, submitting a Pull Request should only happen when the bug fix or feature has been implemented and tested by the submitter.

After making the necessary code changes, the submitter generates a Pull Request on GitHub and marks the bug or feature as Resolved.

A DTVKit moderator reviews a Pull Request marked as Resolved with the intention of marking it Accepted and merging it into the master branch of a DTVKit repository.

The process is typically terminated when the Pull Request has been marked as Accepted by DTVKit and the Mantis ticket closed. If the request can’t be accepted, the Feedback status will be used, along with comments on the pull request itself on Github. Acceptance cannot always be guaranteed. If the Pull Request is marked as Rejected, this is the final stage of a pull request, and will not be accepted. Consequently, the process will terminate by rejection of the Pull Request and closure of the Mantis ticket, or simply by closure of the Mantis ticket.

Creating a pull request from a fork

When you've forked a repository and made changes to the fork, you can ask that the upstream repository accept your branch by creating a pull request.

The branch must be named after the mantis ticket e.g. mantis-xxxx, so that it relates back to the mantis ticket for the fix/feature. The pull request branch must also be on top of the master branch of the DTVKit repository. All changes must be made on a branch so that moderators can test the pull request before accepting it to the master repository.

See also Using the Fork-and-Branch Git Workflow for a step by step guide.

• A pull request should have the minimum set of commits necessary to provide the bug fix or feature.
• Any changes requested should be confined to a single existing commit if the change is to an already modified section of code.
  • Note: For example, you might make a change and commit it and then later on you find that it isn't quite right and so make a fix to the code, in which case the fix should be included in the original commit by using a “fixup” commit and rebasing them.

DTVKit informally defines the compiler warning flags we want to acknowledge via the example_setenv.sh files in each DTVKit repo - App, DVBCore, etc.

CI Plus 1.4 provides this example:

# Additional compiler options

export DTVKIT_ADDITIONAL_COMPILER_OPTIONS=“-Werror -Wall -Wextra -Wcast-align -Wno-unused-parameter \ -Wshadow -Wwrite-strings -Wcast-qual -Wno-missing-field-initializers”

Moderation will reject a pull request that doesn’t build. Warnings should be treated as errors.

If the bug or feature is compliant to DVB standards then the change should be tested prior to submitting the pull request.

A proprietary feature or bug fix that is not compliant to a DVB standard should be tested prior to submitting the pull request. The bug or feature has to be tested when disabled for DVB standard compliance as well as when the (proprietary) feature is enabled.

Pull Requests that provide a bug fix should be able to demonstrate the solution, which may require it to demonstrate the problem. DTVKit has a repository within GitHub called TestStreams that all members have access to. Streams provided in this folder can be used to test the functionality of DTVKit, and have been approved by DTVKit for members to use, in order to test their bug fixes/pull requests.

Before submitting your pull request, please consider the below checklist. Your request is more likely to be moderated and accepted sooner if you have tested and checked the feature/bug fix correctly:

• Tested on 32-bit build of DTVKit
• Tested on 64-bit build of DTVKit
• Check all necessary repositories build without warning errors
• Use the DTVKit provided stream to test with (if this is not suitable, the submitter can use their own stream, however it is highly recommended that they share this stream in Mantis when submitting the request)
• Check the DTVKit desktop App builds
• Check in the App that all expected functionality works:
  • Check you can you scan/tune
  • Check you can change between channels
  • Check the EPG displays with data

After all these checks have been done, we will then deem the fix to be ready for a moderator. When the submitter creates the pull request, they should state what testing has been done, and provide a stream if necessary.