Wiki

Clone wiki

x265_git / Contribute

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 will follow Git's standard branching methodology. The repository will have two named branches, stable and master. The master branch is where all new development will be performed, while the stable branch is for bug fixes only until we get to a release cycle. Each time a bug fix commit is made to stable, that bug fix is merged into the master branch.

When we decide we want to release the contents of the master branch, we merge the master branch onto stable and then begin a short period of heavy testing leading up to a new revision tag being made on the stable branch. Once the tag is made, the master branch is opened again for new development.

Since this is such a young project, there will be no set release tag cadence. It will happen as often as is convenient and necessary, but hopefully at least once a month.

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://bitbucket.org/multicoreware/x265_git 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 <X265TIP>

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.

Finally you can email your patches to the mailing list.

  1. To generate a patch , got 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 <branch-name> <number-of-new-patches> <commit-id of the patch> -o <directory-to-store-patches> * Eg : git format-patch master -1 cd9dda0793c5b874c711eafe5ffde15c0ac208cc -o patches
  4. 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.

Updated