Clone wiki

x265 / 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 Mercurial's standard branching methodology. The repository will have two named branches, stable and default. The default 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 default branch.

When we decide we want to release the contents of the default branch, we merge the default 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 default 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 Mercurial and its
concepts. If you are completely new to distributed revision control,
I recommend reading http://hginit.com. 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 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 based on TortoiseHg, since its partial commit feature
and shelve tool makes this work flow work much more efficient).

  1. Before beginning, open the commit tool, refresh it, and 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.
    CLI: hg status ; hg commit or hg revert

  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: hg pull && hg merge && hg commit

  3. Now update to (checkout) the last (tipmost) pulled changeset. You
    essentially want to checkout the tip of the main x265 repository.
    CLI: hg up -r <X265TIP>

  4. Now that the x265 tip is checked out, you select your tipmost commit
    in the graph and then select a file within that commit, right click
    and select "Revert to Revision..." from the context menu. In the
    revert dialog check "Revert all files to this revision", then click OK.
    CLI: hg revert -a -r <YOURTIP>

After step 4, 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 shelve tool, or revert entire files
via the commit/shelve tool context menus. You can also "shelve" changes into
patch files for later use using the shelve tool. 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
    a) they are easier to review
    b) they are easier to backout, should it be necessary
    c) they make the revision history (particularly annotations) more valuable

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

The TortoiseHg commit tool allows you do de-select files and changes
within files to withold those changes from the commit. In this way you
can iteratively commit your changes into a series of nice clean patches.

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. Select them all in
the revision graph, right click -> Export -> Email patches. The mailing list
is x265-devel@videolan.org, and you need to be a subscriber to submit mail.

Patches intended for the stable branch should be flagged with [STABLE]

See also the TortoiseHg 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.

Experienced Mercurial users will often use MQ and/or rebase for this workflow.
I suggest reading about them if you intend to work on Mercurial projects with
patch based work-flows.

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