Skip to content

Latest commit

 

History

History
224 lines (157 loc) · 7.15 KB

CONTRIBUTING.md

File metadata and controls

224 lines (157 loc) · 7.15 KB
Raw

Contributing to MMOCR

All kinds of contributions are welcome, including but not limited to the following.

  • Fixes (typo, bugs)
  • New features and components

Contents

Workflow

Main Steps

  1. Fork and pull the latest MMOCR
  2. Checkout a new branch (do not use main branch for PRs)
  3. Commit your changes
  4. Create a PR

Note

  • If you plan to add some new features that involve large changes, it is encouraged to open an issue for discussion first.
  • If you are the author of some papers and would like to include your method to MMOCR, please let us know (open an issue or contact the maintainers). We will much appreciate your contribution.
  • For new features and new modules, unit tests are required to improve the code's robustness.

Detailed Steps

The official public repository holds only one branch with an infinite lifetime: main

The main branch is the main branch where the source code of HEAD always reflects a state with the latest development changes for the next release.

Feature branches are used to develop new features for the upcoming or a distant future release.

All new developers to MMOCR need to follow the following steps:

Step 1: Create a Fork

  1. Fork the repo on GitHub or GitLab to your personal account. Click the Fork button on the project page.

  2. Clone your new forked repo to your computer.

git clone https://github.com/<your name>/mmocr.git
  1. Add the official repo as an upstream:
git remote add upstream https://github.com/open-mmlab/mmocr.git

Step 2: Develop a new feature

Step 2.1: Keep your fork up to date

Whenever you want to update your fork with the latest upstream changes, you need to fetch the upstream repo's branches and latest commits to bring them into your repository:

# Fetch from upstream remote
git fetch upstream

# Update your main branch
git checkout main
git rebase upstream/main
git push origin main
Step 2.2: Create a feature branch

  • Create an issue on github

  • Create a feature branch

  • git checkout -b feature/iss_<index> main
# index is the issue index on github above

Step 3: Commit your changes

Develop your new feature and test it to make sure it works well, then commit.

If you have not configured pre-commit hooks for MMOCR, please install pre-commit hooks before your first commit.

The commit message is suggested to be clear. Here is an example:

git commit -m "fix #<issue_index>: <commit_message>"

Step 4: Prepare to Pull Request

  • Before creating an PR, please run

    pre-commit run --all-files
pytest tests

    and fix all failures.

  • Make sure to link your pull request to the related issue. Please refer to the instructon

Step 4.1: Merge official repo updates to your fork
# fetch from upstream remote. i.e., the official repo
git fetch upstream

# update the main branch of your fork
git checkout main
git rebase upstream/main
git push origin main

# update the <your_feature_branch> branch
git checkout <your_feature_branch>
git rebase main
# solve conflicts if any and Test
Step 4.2: Push <your_feature_branch> branch to your remote forked repo,
git checkout <your_feature_branch>
git push origin <your_feature_branch>
Step 4.3: Create a Pull Request

Go to the page for your fork on GitHub, select your new feature branch, and click the pull request button to integrate your feature branch into the upstream remote’s develop branch.

Step 4.4: Review code
Step 4.5: Revise <your_feature_branch> (optional)

If PR is not accepted, pls follow steps above till your PR is accepted.

Step 4.6: Delete <your_feature_branch> branch if your PR is accepted.
git branch -d <your_feature_branch>
git push origin :<your_feature_branch>

Code style

Python

We adopt PEP8 as the preferred code style.

We use the following tools for linting and formatting:

Style configurations of yapf and isort can be found in setup.cfg.

We use pre-commit hook that checks and formats for flake8, yapf, isort, trailing whitespaces, fixes end-of-files, sorts requirments.txt automatically on every commit. The config for a pre-commit hook is stored in .pre-commit-config.

Installing pre-commit hooks

Prerequisite

Make sure Ruby runs on your system.

On Windows: Install Ruby from the official website.

On Debian/Ubuntu:

sudo apt-add-repository ppa:brightbox/ruby-ng -y
sudo apt-get update
sudo apt-get install -y ruby2.7

On other Linux distributions:

# install rvm
curl -L https://get.rvm.io | bash -s -- --autolibs=read-fail
[[ -s "$HOME/.rvm/scripts/rvm" ]] && source "$HOME/.rvm/scripts/rvm"
rvm autolibs disable
# install ruby
rvm install 2.7.1
Installation

After you clone the repository, you will need to install and initialize pre-commit hook.

pip install -U pre-commit

From the repository folder

pre-commit install

After this on every commit check code linters and formatter will be enforced.

Before you create a PR, make sure that your code lints and is formatted by yapf.

C++ and CUDA

We follow the Google C++ Style Guide.