path: root/XServer.mdwn

# X Server Module

Here's a list of other X server related wiki pages 

* [[XorgModuleABIVersions|XorgModuleABIVersions]] 

## X server branches

* [[Server12Branch|Server12Branch]] 
* [[Server13Branch|Server13Branch]] 
* [[Server14Branch|Server14Branch]] 
* [[Server15Branch|Server15Branch]] 
* [[Server16Branch|Server16Branch]] 
* [[Server17Branch|Server17Branch]] 
* [[Server18Branch|Server18Branch]] 
* [[Server19Branch|Server19Branch]] 
* [[Server110Branch|Server110Branch]] 
* [[Server113Branch|Server113Branch]] 
A guideline for what stable branch maintainers need to do is [[here|Development/Documentation/XServerStableBranchManagement]] 


## Development Process

Beginning with [[Server 1.8|Server18Branch]], we have [[changed our development process.|http://lists.freedesktop.org/archives/xorg-devel/2009-September/002330.html]] Below are instructions on how to test and develop on the X server. For stable releases, please refer to the appropriate wiki site (e.g. [[Server113Branch|Server113Branch]]) 

The development process is split into three stages: 

* feature merge window: Starts after the release of the previous version. Features ready will be merged, the server may be unstable during this time. 
* bugfix window: No new features may be merged, only bugfixes and stabilization work is permitted. 
* release freeze: Only bug fixes to go into the pending release may be merged. 
The relevant dates are noted on each server branch page and in the [[X.Org Calendar|http://www.google.com/calendar/embed?src=nl1n1fmvu091eqh35ldqspar80%40group.calendar.google.com&ctz=Australia/Brisbane]]. 


### General information

The development process is now more distributed than it used to be in the past. To explain the process, the following terms are important: 

* **remote**: a repository you cloned from. 
* **master**: the master branch on git.freedesktop.org. This branch will eventually become the new X server. The master branch is in the hands of the release manager. If you are familiar with the kernel development style, think of master being Linus' tree. 
* **personal tree**: a git tree a maintainer has on people.freedesktop.org. These trees are merged into master. A list of these trees are available at [[PersonalTrees|PersonalTrees]].  A personal tree may have multiple branches, only one of which will be merged back to master. See feature branch and devel branch. 
* **feature branch**: a branch on a personal tree devoted to a particular new feature. These feature branches are in development until the feature is deemed ready. Once ready, it can be merged into master during the next feature merge window. 
* **devel branch**: a branch on a personal tree devoted to live development. 
* **rebasing**: rebasing means using git rebase to change the patch order.  Rebasing changes the history and should not be used for any published branch. You are only allowed to rebase local patches not yet pushed or patches you applied with git am (e.g. from a mailing list). If you rebase a branch that has been published and possibly already pulled, you destroy all history and screw everyone downstream from you. 
* **fast-forward/non-fast-forward**: once you clone a git repository, you have the same history as the remote repository. If the remote gets updated by adding commits and you pull from it, you have a fast-forward change. If the remote however rewrites its history (using git rebase), this is a so-called non-fast-forward change. The history has been rewritten and your local copy does not share the same history anymore.  Non-fast-forwards are generally discouraged for any public branch. 

### Users and Testers

Decide what you want to test. This depends on your personal git and development skills but also in what you expect to get from testing. 

If you just want to test the X server in general, the master branch is probably the best for you. The master branch has many temporary patches already pre-tested and thus provides the most stable solution. Master will always be a bit behind the personal trees. 

If you are interested in testing particular subsystems, find the maintainer of that subsystem by browsing the [[PersonalTrees|PersonalTrees]]. Now you have the choice of testing that tree's master branch (more stable, but not as up-to-date) or one of the tree-specific feature branches. 

Testing feature branches means you're at the forefront of development and you help us most by catching bugs early. You can test new, unreleased features, features that may not appear in a released server for another year or even longer. 

Testing a development branch means you can help out the developer by pointing out broken patches. Development branches require some involvement with the developers (otherwise how will you tell them a patch is broken?).  If you catch a bug early enough, the developer will rewrite the patch and thus change the remote's history.  Thus, development branches are are often non-fast-forward. 


### Developers

If you are a developer with no public trees, choose how you want to help out by selecting the appropriate branch to test. Note that it is easy to switch between multiple remotes and branches so you're not bound to a single one. 

Aside from this, the process for you hasn't changed a lot: commit the patch locally, test and send the patch (see [[SubmittingPatches|Development/Documentation/SubmittingPatches]] for some more information) to the xorg-devel list (and/or the maintainer). Keep rebasing regularly from your chosen remote (git pull --rebase). 

The [[MAINTAINERS|http://cgit.freedesktop.org/xorg/doc/xorg-docs/tree/MAINTAINERS]] file has a list of maintainers for a given subsystem. In addition, ajax volunteered to scoop up dangling patches. If your patch isn't picked up in a reasonable time, don't hesitate to ping the list or the maintainer. 


### Maintainers

You are a maintainer if you have a public branch on people.freedesktop. Such a branch is recommended over sending patches one-by-one to the release manager as you will have control over the patches at all times (until the pull request), the patches will see better testing and past experience indicates that pull requests are processed by Keith with a higher priority than patches. 

First, setup up the repository (we're assuming your freedesktop.org username is bond007). 


[[!format txt """
$> git clone git://anongit.freedesktop.org/git/xorg/xserver
$> cd xserver
$> ssh bond007@annarchy.freedesktop.org
annarchy $> mkdir xserver.git
annarchy $> cd xserver.git
annarchy $> GIT_DIR=. git init
annarchy $> touch git-daemon-export-ok
annarchy $> vim description
annarchy $> exit
$> git remote add bond007 git+ssh://bond007@people.freedesktop.org/~bond007/xserver.git
$> git push bond007 master
"""]]
Congratulations, you now have a public master branch in your home directory on freedesktop.org. Add it to the the [[PersonalTrees|PersonalTrees]] list so testers know when and why to pick your tree. For this part, we'll assume your master branch is the branch that's supposed to be merged to git master.  

Note that the "bond007" bit in the git remote command is an arbitrary identifier. You can name it "fdo" (for freedesktop.org), after your username, or after your favourite color. The important thing is that you remember what git push bond007 means when you run it (i.e. where you're pushing to). 


#### Scooping up patches

Scoop up patches from the list that apply to your area of work when you've reviewed them. Simply pipe the patch into "git am -s" should do in most cases. Let the developer know that you've scooped it up, it saves others from doing the same. If there are multiple ACKs or Reviewed-by on the list, please add them to the patch so we have a record of who looked at the patch. It doesn't have to be a perfect record, remember that once you pushed your tree you can't amend the patches anymore, even if a late Reviewed-by comes in. 

Once you have scooped up a patch, push it to the matching branch in your personal repository. A simple git push does in most cases but see below for more details. Hint: if you haven't synced with master for a while, it's better to rebase master before pushing. 


#### Pushing to your personal tree

Syncing with master often is encouraged. This way, testers of your personal tree also test recent patches in master. Also, it's one way to keep testers as they are less inclined to switch to other branches if they get fixes from others soon enough anyway. To sync your personal tree, either pull or rebase from master. **You can only ever rebase if the last state of your personal tree has been pulled into master already.** Rebasing destroys history, so you can only ever do it when the history being destroyed is not public (i.e. only on your local box). 

If bond007/master has been pulled by the RM: 
[[!format txt """
$> git pull --rebase
$> git am -s <patches from list>
# test
$> git rebase -i origin/master # if you need to reshuffle something
$> git push bond007 master
"""]]
If bond007/master has **not** been pulled (e.g. you are accumulating a few patches before sending the pull request): 
[[!format txt """
$> git pull origin # if you need to sync with master
$> git am -s <patches from list>
# test
$> git rebase -i <merge commit from pull> # if you need to reshuffle something
$> git push bond007 master
"""]]

#### Your own patches

Your own patches follow the same process as others, send it to the list for review, then merge them accordingly once the Reviewed-by comes in. We should demand the same level of review from each other as from casual contributors. 


#### Getting Patches and Pulls merged into master

Again, you are encouraged to have your own branch on freedesktop.org. Once a patch has a Reviewed-by tag, pull this patch into your branch and at the appropriate time, push the branch to freedesktop.org and request a pull from the release manager. The pull must have a [PULL] in the subject line and make sure you Cc: the release manager in your email. For 1.9, the release manager is [[keithp@keithp.com|mailto:keithp@keithp.com]]. 

If a patch should be merged to master directly instead of going through a personal tree and a pull request, make sure you state so in the patch email and the release manager is on the CC list. 

Patches will not automatically be accepted; make sure there has been sufficient review, and that the reviewers have added their Reviewed-by: line to the commit message. Of course, patches may also be rejected for almost any other reason; the release manager is known to be somewhat arbitrary and capricious at times. 

Use [[git-request-pull|http://www.au.kernel.org/software/scm/git/docs/git-request-pull.html]] to get the standard email for a pull request. 


[[!format txt """
$> git request-pull 12345deadbeef git://people.freedesktop.org/~bond007/xserver.git
"""]]
Where 12345deadbeef refers to the last commit from the master branch. Pull requests (and patches in general) may get lost. If no reason for not pulling/applying has been given, poke the release manager again. 

There is no minimum number of patches for pull requests, a pull request for a single patch is fine. All patches included in a pull request should have a Reviewed-by line. 


#### Development branches

Developing intermediate patches are best done on a separate branch. This branch may be non-fast-forward if needed (document this for users!). The situation to avoid is that a number of patches have accumulated in your tree that need to be merged into master but there's other in-development patches that prevent it from being pulled. Keep ongoing work separate from the trees to be pulled. 


### Patchwork

The [[xorg patchwork|http://patchwork.freedesktop.org/project/Xorg/list/]] installation keeps track of patches. Note that to change the state of a patch in patchwork requires manual interaction, it does not get updated automatically as patches are pulled into the tree.