Skip to content

Latest commit

 

History

History
91 lines (75 loc) · 10.3 KB

CONTRIBUTING.md

File metadata and controls

91 lines (75 loc) · 10.3 KB

Contributing to AugLy

We want to make contributing to this project as easy and transparent as possible.

Pull Requests

We actively welcome your pull requests.

  1. Fork the repo and create your branch from main.
  2. If you've added code that should be tested, add tests.
  3. If you've changed APIs, update the documentation.
  4. Ensure the test suite passes.
  5. Make sure your code lints.
  6. Run black formatting.
  7. If you haven't already, complete the Contributor License Agreement ("CLA").

Adding a New Augmentation

Before adding a new augmentation, please open an associated issue such that we could ensure that (a) this functionality doesn't already exist in the library (b) it is in line with the kinds of augmentations we'd like to support.

Please implement your new augmentation using AugLy's existing dependencies (i.e. PIL, numpy, nlpaug, librosa, etc.) if possible, and avoid adding new dependencies as these will make AugLy heavier and slower to download. However, if you feel it's necessary in order to implement your new augmentation and that the new augmentation is really worth having, it may be fine; in this case, add your new dependency to requirements.txt, and then make sure you can install augly in a fresh conda environment and the new unit tests pass.

Before submitting a PR with your new augmentation, please ensure that you have made all the necessary changes in the listed files below for the corresponding module where you're adding the augmentation. Whenever adding a new function, class, etc please make sure to insert it in alphabetical order in the file!

Audio

  • augly/audio/functional.py (e.g. changes for pitch_shift)
  • augly/audio/transforms.py (e.g. changes for pitch_shift)
  • augly/audio/intensity.py (e.g. changes for pitch_shift)
  • augly/audio/__init__.py (e.g. changes for pitch_shift)
  • augly/tests/audio_tests/functional_unit_test.py (e.g. changes for pitch_shift)
  • augly/tests/audio_tests/transforms_unit_test.py (e.g. changes for pitch_shift)
  • augly/utils/expected_output/audio/expected_metadata.json (e.g. changes for pitch_shift)
  • augly/assets/tests/audio/speech_commands_expected_output/{mono, stereo}/test_<aug_name>.wav (e.g. mono & stereo files for pitch_shift)
    • These test files should be the result of running the new augmentation with the args as specified in the new unit tests. The two new unit tests should specify the same args for the new augmentation so they can use the same output file.

Image

  • augly/image/functional.py (e.g. changes for crop)
  • augly/image/transforms.py (e.g. changes for crop)
  • augly/image/intensity.py (e.g. changes for crop)
  • augly/image/__init__.py (e.g. changes for crop)
  • augly/tests/image_tests/functional_unit_test.py (e.g. changes for crop)
  • augly/tests/image_tests/transforms_unit_test.py (e.g. changes for crop)
  • augly/utils/expected_output/image/expected_metadata.json (e.g. changes for crop)
  • augly/assets/tests/image/dfdc_expected_output/test_<aug_name>.png (e.g. test file for crop)
    • This test file should be the result of running the new augmentation with the args as specified in the new unit tests. The two new unit tests should specify the same args for the new augmentation so they can use the same output file.
  • augly/image/utils/bboxes.py (e.g. changes for crop)
    • You should ensure that bounding boxes will be correctly transformed with the images for your new augmentation by either (1) adding a new helper function to bboxes.py which computes how a given bounding box will be changed by your augmentation (see the one for crop as an example); (2) using the spatial_bbox_helper if your augmentation is spatial and does not cause any color changes or overlay non-black content (see skew call it as an example); or (3) doing nothing if your new augmentation does not move or occlude pixels at all from the original image content (e.g. color_jitter or sharpen).

Text

  • augly/text/functional.py (e.g. changes for split_words)
  • augly/text/transforms.py (e.g. changes for split_words)
  • augly/text/intensity.py (e.g. changes for split_words)
  • augly/text/__init__.py (e.g. changes for split_words)
  • augly/tests/text_tests/functional_unit_test.py (e.g. changes for split_words)
  • augly/tests/text_tests/transforms_unit_test.py (e.g. changes for split_words)
  • augly/utils/expected_output/text/expected_metadata.json (e.g. changes for split_words)

Video

  • augly/video/functional.py (e.g. changes for overlay)
  • augly/video/transforms.py (e.g. changes for overlay)
  • augly/video/__init__.py (e.g. changes for overlay)
  • augly/video/helpers/intensity.py (e.g. changes for overlay)
  • augly/video/helpers/__init__.py (e.g. changes for overlay)
  • augly/tests/video_tests/transforms/<aug_type>.py (e.g. changes for overlay)
    • Instead of functional_unit_test.py or transforms_unit_test.py, you should choose which test file to add the unit test for your new augmentation to based on which category it best fits in to. If the augmentation is implemented using cv2 or ffmpeg, you should add the unit test to cv2_test.py or ffmpeg_test.py respectively. If the augmentation is implemented by applying a function to each frame of the video, you should add the unit test to image_based_test.py. If the augmentation is a combination of multiple video augmentations, you should add the unit test to composite_test.py.
  • augly/utils/expected_output/image/expected_metadata.json (e.g. changes for overlay
  • You may also need to add an augmenter file in augly/video/augmenters/ if your augmentation uses cv2 or ffmpeg (e.g. changes for overlay)

Contributor License Agreement ("CLA")

In order to accept your pull request, we need you to submit a CLA. You only need to do this once to work on any of Facebook's open source projects.

Complete your CLA here: https://code.facebook.com/cla

Issues

We use GitHub issues to track public bugs. Please ensure your description is clear and has sufficient instructions to be able to reproduce the issue.

Facebook has a bounty program for the safe disclosure of security bugs. In those cases, please go through the process outlined on that page and do not file a public issue.

Coding Style

  • 4 spaces for indentation rather than tabs
  • 90 character line length
  • 2 newlines before a function or class definition. For functions within classes, use a single newline
  • Add typing to your function parameters and add a return type
  • Add a newline after an if/else block

License

By contributing to AugLy, you agree that your contributions will be licensed under the LICENSE file in the root directory of this source tree.