How to contribute changes back to x265?
See our TODO page for work that needs to be done, and what is currently in progress
We use a mailing list to communicate and review patches:
- IRC: #x265 on freenode
- devel list: email@example.com
- commit list: firstname.lastname@example.org
- patchworks: http://patches.videolan.org/project/x265-devel/list/
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.
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.
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).
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
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
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>
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.
Make a meaningful commit message. The first line should be a quick summary. If necessary, add a blank line and then a longer explanation.
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
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 email@example.com, 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:
- re-clone from x265 and discard your old repo
- pull from x265 and close or strip your old development head
- pull from x265 and mark your old development head with phase secret
- 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.
- x265.h needs good documentation
- x265_param_parse() must be updated
- x265_param2string() must be updated
- getopt() (and CLI help) support needs to be added to x265cli.h
- the param must be documented in doc/reST/cli.rst
- X265_BUILD must be incremented, the binary interface has changed
- 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.