====== Graphics stack: ports development workflow ======

===== Clone the repository and setup remote repositories =====

  - Clone the Ports development repository:

<code>
git clone https://github.com/freebsd/freebsd-ports-graphics.git
</code>

  - If you have write access to this repository, change the push URL:

<code>
git remote set-url --push origin git@github.com:freebsd/freebsd-ports-graphics.git}}}
 1. Add the official Ports tree mirror as a second remote repository, called `upstream`: {{{
git remote add upstream https://github.com/freebsd/freebsd-ports.git}}}

The `master` branch (the default one) matches the official Potree tree Subversion repository. This branch must stay untouched: never commit anything on this one!

== Keep the "master" branch up-to-date ==

The `upstream` repository is used to fetch new changes made to the Ports tree Subversion repository. Your local `master` branch is a copy of this mirror, not a "symlink". You need to keep it up-to-date yourself. To do this:
 1. Make sure you sit on the "master" branch: {{{
git checkout master}}}
 1. Fetch changes from the upstream repository (ie. the official Git mirror): {{{
git fetch -p upstream}}}
 1. Update your local copy: {{{
git merge --ff-only upstream/master}}}
 1. Optionaly, push this up-to-date copy to the `origin` repository (xorg-dev): {{{
git push}}}

== Example: work on xorg-server 1.14 ==

=== Work with a topic branch ===

To ease the work on parallel non-related tasks, it's better to use topic branches, instead of a single branch receiving everything, like we did in the old xorg-dev Subversion repository. Here, we take an update to the xorg-server as an example.

 1. Create the topic branch. This will create a branch called `xorg-server-1.14`, based on your local `master` branch. It's a good thing to update this `master` branch before, to permit you to work on a fresh up-to-date Ports tree. {{{
git checkout -b xorg-server-1.14 master}}}
 1. At this point, your local working copy is the `xorg-server-1.14` branch, not the `master` branch. You can make whatever modifications you need to `x11-servers/xorg-server` to update it to 1.14.
 1. Commit your changes: {{{
git add x11-servers/xorg-server
git commit}}}
 1. Do this as often as you need/want
 1. When your work is ready to be shared, push it to the public development repository: {{{
git push -u origin xorg-server-1.14:xorg-server-1.14}}}
 1. The `-u` flag is here to save you some typing the next time you push. That's why you can make new changes, commit them and push your work again: {{{
git push}}}

=== Get changes from other developers ===

If other people are working on the same branch with you, you'll have to fetch their changes: {{{
git pull -r}}}

You can continue to work and commit, then push.

=== Generate the final patch ===

When xorg-server 1.14 is stable and ready to hit the official Ports tree, you must generate the final patch:
 1. Update your `master` branch as shown above
 1. Go back to your topic branch: {{{
git checkout xorg-server-1.14}}}
 1. Merge the `master` branch: {{{
git merge master}}}
 1. Generate the patch: {{{
git diff master...xorg-server-1.14 > xorg-server-1.14.patch}}}

</code>