Graphics stack: ports development workflow

Clone the repository and setup remote repositories

  1. Clone the Ports development repository:

    git clone https://github.com/freebsd/freebsd-ports-graphics.git
  2. If you have write access to this repository, change the push URL:

    git remote set-url --push origin git@github.com:freebsd/freebsd-ports-graphics.git
  3. 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
  2. Fetch changes from the upstream repository (ie. the official Git mirror):

    git fetch -p upstream
  3. Update your local copy:

    git merge --ff-only upstream/master
  4. 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
  2. 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.

  3. Commit your changes:

    git add x11-servers/xorg-server
    git commit
  4. Do this as often as you need/want
  5. 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
  6. 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

  2. Go back to your topic branch:

    git checkout xorg-server-1.14
  3. Merge the master branch:

    git merge master
  4. Generate the patch:

    git diff master...xorg-server-1.14 > xorg-server-1.14.patch

GraphicsOld/Ports development workflow (last edited 2018-11-26T01:31:36+0000 by PeteWright)