Submitting Pull Request(PR) Guidelines:¶

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

Clone branch for PR¶

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

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

# pull any recent updates
git pull

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

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 DeFFcode 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 master 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 of the DeFFcode APIs 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 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. For more information, see this doc➶

Testing, Formatting & Linting¶

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

Requirements¶

Testing DeFFcode 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:

  # Install opencv(only if not installed previously)
  $ pip install opencv-python
  
  # install rest of dependencies
  $ pip install --upgrade flake8 black pytest vidgear[core]
  

• 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:

  On Linux/MacOSOn Windows

  $ chmod +x scripts/bash/prepare_dataset.sh
  $ ./scripts/bash/prepare_dataset.sh
  

  $ sh scripts/bash/prepare_dataset.sh
  

Running Tests¶

All tests can be run with pytest(in DeFFcode'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: DeFFcode 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 DeFFcode 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!