Submitting Pull Request(PR) Guidelines:¶

The following guidelines tells you how to submit a valid PR for vidGear:

Clone Testing branch¶

You can clone your Forked remote git to local and create your PR working branch as a sub-branch of latest testing branch as follows:

Functions of different VidGear's Github Branches

Following are the base branches for VidGear's code in its Github Repository:

Master/MainTestingDevelopment

Branch Features:

• Most-Stable
• Includes the latest stable-release.
• Lacks any latest bug-fixes and changes.
• Everything CI tested.

Cloning:

# clone your forked repository and `cd` inside
git clone https://github.com/abhiTronix/vidgear.git && cd vidgear

Branch Features:

• Stable.
• Includes latest stable bug-fixes and changes.
• Used for pushing PR commits.
• Everything CI tested.

Cloning:

# clone your forked repository and `cd` inside
git clone https://github.com/abhiTronix/vidgear.git && cd vidgear

# checkout the latest testing branch
git checkout testing

Branch Features:

• Unstable.
• Includes latest experimental changes.
• Used for pushing experimental commits.
• Nothing CI tested.

Cloning:

# clone your forked repository and `cd` inside
git clone https://github.com/abhiTronix/vidgear.git && cd vidgear

# checkout the latest development branch
git checkout development

Workflow:

Typically any feature/improvement/bug-fix code flows as follows:

# clone your forked repository(change with your username) and get inside
git clone https://github.com/{YOUR USERNAME}/vidgear.git && cd vidgear

# pull any recent updates
git pull

# checkout the latest testing branch
git checkout testing

# Now create your new branch with suitable name(such as "subbranch_of_testing")
git checkout -b subbranch_of_testing

Now after working with this newly created branch for your Pull Request, you can commit and push or merge it locally or remotely as usual.

PR Submission Checklist¶

There are some important checks you need to perform while submitting your Pull Request(s) for VidGear library:

• Submit a Related Issue:

• The first thing you do is submit an issue with a proposal template for your work first and then work on your Pull Request.

• Submit a Draft Pull Request:

• Submit the draft pull request from the first day of your development.

• Add a brief but descriptive title for your PR.
• Explain what the PR adds, fixes, or improves.
• In case of bug fixes, add a new unit test case that would fail against your bug fix.
• Provide output or screenshots, if you can.
• Make sure your pull request passed all the CI checks (triggers automatically on pushing commits against testing branch). If it's somehow failing, then ask the maintainer for a review.

• Click "ready for review" when finished.

• Test, Format & lint code locally:

• Make sure to test, format, and lint the modified code locally before every commit. The details are discussed below ➶

• Make sensible commit messages:

• If your pull request fixes a separate issue number, remember to include "resolves #issue_number" in the commit message. Learn more about it here ➶.

• Keep the commit message concisely as much as possible at every submit. You can make a supplement to the previous commit with git commit --amend command.

• Perform Integrity Checks:

  Any duplicate pull request will be Rejected!

• Search GitHub if there's a similar open or closed PR that relates to your submission.

• Check if your purpose code matches the overall direction, simplicity, and structure of the VidGear and improves it.

• Retain copyright for your contributions, but also agree to license them for usage by the project and author(s) under the Apache 2.0 license ➶.

• Link your Issues:

  For more information on Linking a pull request to an issue, See this wiki doc➶

• Finally, when you're confident enough, make your pull request public.

• You can link an issue to a pull request manually or using a supported keyword in the pull request description. It helps collaborators see that someone is working on the issue.

Testing, Formatting & Linting¶

All Pull Request(s) must be tested, formatted & linted against our library standards as discussed below:

Requirements¶

Testing VidGear requires additional test dependencies and dataset, which can be handled manually as follows:

• Install additional python libraries:

  You can easily install these dependencies via pip:

  MPEGDASH for Windows

  The mpegdash library has not yet been updated and bugs on windows machines. Therefore install the forked DEV-version of mpegdash as follows:

  python -m pip install https://github.com/abhiTronix/python-mpegdash/releases/download/0.3.0-dev2/mpegdash-0.3.0.dev2-py3-none-any.whl
  

  pip install --upgrade six flake8 black pytest pytest-asyncio mpegdash paramiko m3u8 async-asgi-testclient
  

• Download Tests Dataset:

  To perform tests, you also need to download additional dataset (to your temp dir) by running prepare_dataset.sh bash script as follows:

  chmod +x scripts/bash/prepare_dataset.sh
  # On linux and MacOS
  .scripts/bash/prepare_dataset.sh
  # On Windows 
  sh scripts/bash/prepare_dataset.sh
  

Running Tests¶

All tests can be run with pytest(in VidGear's root folder) as follows:

 pytest -sv  #-sv for verbose output.

Formatting & Linting¶

For formatting and linting, following libraries are used:

• Flake8: You must run flake8 linting for checking the code base against the coding style (PEP8), programming errors and other cyclomatic complexity:

  flake8 {source_file_or_directory} --count --select=E9,F63,F7,F82 --show-source --statistics
  

• Black: Vidgear follows black formatting to make code review faster by producing the smallest diffs possible. You must run it with sensible defaults as follows:

  black {source_file_or_directory}
  

Frequently Asked Questions¶

Q1. Why do my changes taking so long to be Reviewed and/or Merged?

Pull requests will be reviewed by the maintainers and the rationale behind the maintainer’s decision to accept or deny the changes will be posted in the pull request. Please wait for our code review and approval, possibly enhancing your change on request.

Q2. Would you accept a huge Pull Request with Lots of Changes?

First, make sure that the changes are somewhat related. Otherwise, please create separate pull requests. Anyway, before submitting a huge change, it's probably a good idea to open an issue in the VidGear Github repository to ask the maintainers if they agree with your proposed changes. Otherwise, they could refuse your proposal after you put all that hard work into making the changes. We definitely don't want you to waste your time!