Skip to content

Contribute

Jump to bottom
kirithika7 edited this page Jul 15, 2026 · 37 revisions

How to contribute changes back to x265?

See our TODO page for work that needs to be done, and what is currently in progress

Communications

We use a mailing list to communicate and review patches:

Contributor License Agreement

As is common for Open Source projects, we require a signed contributor agreement before we can accept changes. This protects the project from being sued by former contributors (or their employers) for copyright or patent infringement.

You must download the document, fill it in, return it to us by one of the methods described in the document. We will countersign and return it to you. You only need to do this once.

Release Management

x265 follows a Trunk-Based Development (TBD) workflow. All development is integrated into the master branch through pull requests or reviewed mailing-list patches. Contributors are expected to keep their branches short-lived and regularly rebase on the latest master to minimize integration conflicts.

Every change merged into master must pass the project's continuous integration (CI) checks, including builds for all supported bit-depth configurations and the relevant test suites. This ensures that master remains in a releasable state.

When preparing a release, the release is cut directly from a stable point on the master branch. Release candidates may undergo additional validation and testing before an official version tag is created. Bug fixes identified during release validation are merged into master following the normal review process, ensuring that the release and ongoing development remain on a single development line.

There is no long-lived stable development branch. Maintenance releases, if required, are created by tagging appropriate commits from master (or from a temporary release branch, when necessary). This simplifies development, reduces merge overhead, and ensures that all contributors work against a single source of truth.

Patch generation

This section assumes you have a working knowledge of GIT and its concepts. If you are completely new to distributed revision control, I recommend reading https://git-scm.com/docs/git. If you are familiar with git and unfamiliar with Mercurial, this Mercurial Wiki page can explain how git concepts map to Mercurial. This blog post about git and hg may also be helpful.

The first rule for contributing changes is to never develop from a downloaded source package. Always clone the x265 main repository at https://github.com/Multicorewareinc/x265 and then develop within your cloned repository so your changes can be revisioned controlled from the beginning.

A primary principle of distributed revision control is that every developer with a clone has full and total access to the revision history. Even though you probably do not have push rights for the main repository, you are the king over your local clone. You can examine history, checkout old revisions, make new commits, make entirely new clones, etc.

For most people, contributing a change to x265 will be an iterative process. You will make some changes and commit them. In the simplest case, if all your commits happen to have been made on top of the latest x265 tip, then you can simply email those commits to our mailing list.

However, most of the time you will make multiple commits and you might then pull in new changesets from the main x265 repository and merge with them (and commit the merge). And you might then make more commits and repeat. By the time your changes are ready for public distribution, you might have dozens of commits and several merges with incoming changes. Here is how you tidy up all your work for submission to our mailing list, the primary goal here is to rebase all of your changes on top of the current x265 tip so your patches will apply cleanly on the maintainer's repository:

(these instructions are recommended to be done on terminal (either windows commnand prompt/git bash terminal/ if windows OS or linux terminal in case of Linux OS or ios terminal incase of iOs)

  1. Before beginning , make sure all of your changes have been checked in, or reverted if you did not want to keep them. You must start with a clean working directory. Login to the terminal and go to the folder which contains the repository. CLI: git status ; git commit or git reset --hard

  2. Ensure your changes have been merged with the tip of x265. Do a pull just to be sure, and merge with any newly pulled changesets. CLI: git fetch && git merge or git pull

  3. Now update to (checkout) the last (tipmost) pulled changeset. You essentially want to checkout the tip of the main x265 repository. CLI: git checkout

After step 3, your working directory parent revision (the basis of your new commits) will be the current x265 tip revision and all of the accumulated commits you have made to your x265 source tree will appear as new diffs. At this point you can review all of the changes you have made. You can remove inadvertent changes using the git stash command that temporarily shelves (or stashes) changes you've made to your working copy so you can work on something else, and then come back and re-apply them later on, or revert entire files using command git reset --hard.Once you are happy with the diffs you see in the commit tool, you can begin making new clean commits.

  1. Make a meaningful commit message. The first line should be a quick summary. If necessary, add a blank line and then a longer explanation.

  2. Small coherent commits are better than one large commit, for many reasons

    • they are easier to review

    • they are easier to backout, should it be necessary

    • they make the revision history (particularly annotations) more valuable

  3. Separate white-space changes from logic changes. Commits should never do both

Now build and test the last commit to ensure all tests pass, etc. If any performance improvements are intended, the amount gained should be included in the email subject or body, or in the commit message itself.

Patch Submission

Option A:GitHub Pull Request (Recommended) Fork the repository (external contributors) or create a topic branch (maintainers) from the latest master. Implement your changes and keep the pull request focused on a single logical change. Verify that the project builds successfully in all supported bit-depth configurations and that TestBench passes for the modified architectures. Run: git clang-format origin/master Open a pull request targeting the master branch. The CI pipeline will automatically build all supported configurations and execute the CLI, regression, and threading test suites. Address review comments by pushing follow-up commits. Maintainers may squash commits during merge.

Option B:Mailing List The traditional VideoLAN mailing-list workflow remains fully supported and is well suited for patch series.

  1. To generate a patch , go to the repository folder in your terminal.
  2. Make sure you have committed your changes . Check this by issuing git log and verify if your new commit appears on top.
  3. Once your new commit is seen , use the format-patch command to generate patches CLI :git format-patch -o
  • Eg : git format-patch master -1 cd9dda0793c5b874c711eafe5ffde15c0ac208cc -o patches
  1. You should be able to see your new patches in the directory which was mentioned . The patches will have the commit message of the specific commit

Now build and test the last commit to ensure all tests pass, etc. If any performance improvements are intended, the amount gained should be included in the email subject or body, or in the commit message itself.

The mailing list is x265-devel@videolan.org, and you need to be a subscriber to submit mail.

Patches for a branch should be flagged with branch name Eg: [MASTER]

See also the Git manual

Once you email these patches to the mailing list, you merge your new patch commit(s) with your previous tip and then you can continue development. If your changes are rejected you can fix the identified problems, make new commits, and then restart at step 1.

If your changes were accepted, and pushed to x265, then you have a few options for continuing on:

  1. re-clone from x265 and discard your old repo
  2. pull from x265 and close or strip your old development head
  3. pull from x265 and mark your old development head with phase secret
  4. pull from x265, update to the incoming tip, ignore your old development head

In any case, you want to discard your old line of development and start your new work from the current x265 tip.

Maintenance of Hg repository

Once your patch is approved and pushed to the x265 Git repository, we have automated the process of getting all the new patches from the git repository and importing & pushing it to the respective branch of x265 Hg repository. By this way we ensure both the VCS are in sync and up to date.

API Change Responsibilities

If you introduce a new x265_param member, you must add documentation for it and make it fully configurable.

  1. x265.h needs good documentation
  2. x265_param_parse() must be updated
  3. x265_param2string() must be updated
  4. getopt() (and CLI help) support needs to be added to x265cli.h
  5. the param must be documented in doc/reST/cli.rst
  6. X265_BUILD must be incremented, the binary interface has changed
  7. test(s) have to be added to smoke-tests.txt and regression-tests.txt

Much of the above is also true if you change any public function definitions or public structures.

Clone this wiki locally