Skip to content

AVM: Software Development Workflow

Jump to bottom
urvangjoshi edited this page May 19, 2026 · 31 revisions

Software Development Workflow for Pull Requests

This page details typical Git-based software development workflow for Pull Requests (PRs) related to integration of adopted tools, bug fixes, clean-ups or other software/infrastructure related changes. Please contact software coordinators for any issues or non-typical software integration needs.

Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. There are plenty of free online resources available to get familiar with Git such as

  1. The Git Community Book, Getting-Started-First-Time-Git-Setup
  2. The Github help

Specifically, the project will use the project forking workflow.

1. One-time Setup

(a) GitHub registration and software repository 

A GitHub account can be registered @ https://github.com/signup. It is recommended to register using your company email address to aid in quick verification. 

The official project repository is located at @ https://github.com/AOMediaCodec/avm.

The repository has open read access for every user and restricted access to make software changes or raise pull requests. For questions related to repository access and/or permission levels please contact the software coordinators or codec working group chairs.

Setup SSH key(s) if you plan to push / pull via SSH: https://github.com/settings/keys

(b) Create your own fork

Follow the GitHub guide available here:

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo

(c) Clone your fork locally

Clone the forked repository locally:

git clone https://github.com/[namespace]/avm.git
  • This will automatically create a remote called ‘origin’ pointing to your fork

Add remote called ‘upstream’, pointing to the official repository:

git remote add upstream https://github.com/AOMediaCodec/avm.git

RECOMMENDED: Force fast-forward only mode for git pull

git config --global pull.ff only

2. Develop a tool / feature / bugfix in your fork

  • In your local repository, create a feature branch

    git checkout -b <branch_name>

  • Make required changes following the best practices and coding style.

  • Commit your changes locally

    git add <file(s)>
git commit

  • Push changes to your fork, with the same branch name:

    git push -u origin <branch_name>

2.1 Update a feature branch

Additional commits can later be pushed to the same branch as follows:

git add <file(s)>
git commit
git push

Note that in the recommended method above, new commits are created and pushed. Later, the pushed commits are by default squashed before an PR is merged.

3. Create a pull request (PR) 

After you are ready to merge your changes to the official repository, create a new pull request in the web UI: https://github.com/AOMediaCodec/avm

Follow the GitHub guide available here: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request.

  • Select appropriate “Source branch” and “Target branch”
    • Source branch is the new experiment branch in your own fork, and
    • Target branch is the place where the code is going to be merged to (e.g. ‘main’ branch in the official repository)
  • Click “Compare branches and continue”. You should see an entry similar to: New Pull Request → From source-branch into target-branch. An entry like this confirms your pull request’s destination.
  • Fill in the title and descriptions following guidelines here: https://github.com/AOMediaCodec/avm/wiki/Guidelines-for-PR-Title-and-Description
  • The CI/CD process will be automatically invoked for every submitted PR.

3.1 Update a Pull Request

Reviewers / Software Coordinators may provide comments on the PR that need to be addressed before merging.

If so, the PR may be updated as follows:

  1. Checkout same git branch locally: git checkout <branch_name>
  2. Create and push additional commit to the same remote branch using git add + commmit + push commands as described in section 2.1.
  3. This will automatically update the pull request: no further action is required.

Note: If a git rebase / amend operations are used during update in step 2, then a forced push may be required:

git push origin --force

Once the PR is approved, one of the software co-ordinators will merge them.

3.2 Collaborate on a tool / feature:

Sometimes a tool / feature may be non-trivial and may require multiple contributors. In such a scenario, a dedicated feature branch may be created for collaboration. Multiple developers can then contribute to this feature branch without affecting the functionality of the ‘main’ branch.

To achieve this, create a pull request (PR) using the same process as described in section 3. However, select this feature branch as the “Target branch” (instead of ‘main’). When your PR is approved and merged, the changes are incorporated directly into the feature branch.

Later, when the feature branch is ready to be merged to the official repository, a new PR can be created targeting the ‘main’ branch.

4. Update your fork

To avoid merge conflicts, you may want to update your fork:

  • Once your PRs have been merged to the official repository, and
  • Periodically to pull other changes from the official repository

You can do that as follows:

  • Pull latest changes from official repository (‘upstream’) locally:

    git checkout main
git pull upstream main

  • Push the changes to your forked repository (‘origin’):

    git push origin main

  • Prune local branches no longer on forked and upstream repositories:

    git fetch --all && git fetch --prune

  • Rebase any local branches if needed

    git checkout test_branch
git rebase main

  • Fetch any new tags

    git fetch -t upstream

Clone this wiki locally