mmocr/docs/contributing.md

Contributing to mmocr

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

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

Workflow

This document describes the fork & merge request workflow that should be used when contributing to MMOCR.

The official public repository holds two branches with an infinite lifetime only:

• master
• develop

The master branch is the main branch where the source code of HEAD always reflects a production-ready state.

The develop branch is the 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: creating 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

3. 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: keeping 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 master branch
git checkout master
git rebase upstream/master
git push origin master

# Update your develop branch
git checkout develop
git rebase upsteam/develop
git push origin develop

Step 2.2: creating a feature branch

git checkout -b <your_new_feature> develop

Till now, your fork has three branches as follows:

Step 2.3: develop and test <your_new_feature>

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

Pls run

pre-commit run --all-files
pytest tests

and fix all failures before every git commit.

Step 2.4: prepare to PR

Merge official repo updates to your fork

# fetch from upstream remote. i.e., the official repo
git fetch upstream

# update the develop branch of your fork
git checkout develop
git rebase upsteam/develop
git push origin develop

# update the <your_new_feature> branch
git checkout <your_new_feature>
git rebase develop
# solve conflicts if any and Test

Push <your_new_feature> branch to your remote forked repo,

git checkout <your_new_feature>
git push origin <your_new_feature>

Step 2.5: send PR

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 2.6: review code

Step 2.7: revise <your_new_feature> (optional)

If PR is not accepted, pls follow Step 2.1, 2.3, 2.4 and 2.5 till your PR is accepted.

Step 2.8: del <your_new_feature> branch if your PR is accepted.

git branch -d <your_new_feature>
git push origin :<your_new_feature>

Code style

Python

We adopt PEP8 as the preferred code style.

We use the following tools for linting and formatting:

• flake8: linter
• yapf: formatter
• isort: sort imports

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.