Submitting Pull Request(PR) Guidelines:¶
The following guidelines tells you how to submit a valid PR for vidGear:
Working on your first Pull Request for VidGear?
-
If you don't know how to contribute to an Open Source Project on GitHub, then You can learn about it from here ➶
-
If you're stuck at something, please join our Gitter community channel. We will help you get started!
-
Kindly follow the EXEMPLARY tag for some finest PR examples.
Clone Testing branch¶
Base Branch must be testing
in your Pull Request
Every PR MUST be pushed against VidGear's testing
branch only, in order to trigger must needed CI testing workflows. If your's not, then change the base branch to testing
➶
Make sure the testing
branch of your Forked repository is up-to-date with VidGear, before starting working on Pull Request.
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:
Branch Features:
- Most-Stable
- Includes the latest stable-release.
- Lacks any latest bug-fixes and changes.
- Everything CI tested.
Cloning:
Branch Features:
- Stable.
- Includes latest stable bug-fixes and changes.
- Used for pushing PR commits.
- Everything CI tested.
Cloning:
Branch Features:
- Unstable.
- Includes latest experimental changes.
- Used for pushing experimental commits.
- Nothing CI tested.
Cloning:
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 ofmpegdash
as follows: -
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:
Running Tests¶
All tests can be run with pytest
(in VidGear's root folder) as follows:
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: -
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:
Frequently Asked Questions¶
Q1. Why do my changes taking so long to be Reviewed and/or Merged?
Submission Aftermaths
- After your PR is merged, you can safely delete your branch and pull the changes from the main (upstream) repository.
- The changes will remain in
testing
branch until next VidGear version is released, then it will be merged intomaster
branch. - After a successful Merge, your newer contributions will be given priority over others.
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!