Using Git within the Xfce development workflow

• Introduction
• Setting your Git credentials
• Git usage example on an Xfce project
• Commit Guidelines
• GitLab Forks and Merge Requests
• Git rules on gitlab.xfce.org
• Git repository description
• Xfce GitHub mirror

Xfce uses Git as distributed version control system (DCVS) for all the code contributed by developers. On this page, we will explain the basics and initial setup needed to get started developing for Xfce. However, if you want to know it all about Git, look at the following websites for a more in depth examination of Git and its usage:

• Official books and reference manual
• Official Git tutorial
• Git Reference (via GitHub)
• Use man git <command> in your terminal emulator
• Your favorite search engine

• Tips and Tricks – Some additional functionality that is nice to know.

• GitHub mirror – What we do with the GitHub mirror of the Xfce repositories.

Before you even think about committing changes, you must set your name and email address to something valid in your local Git config:

git config --global user.name "J. Random Hacker"
git config --global user.email "jrandom@example.com"

Make sure the email address is a valid address, there is a hook on the server that checks the address of every new commit.

Back To Top

The intention, here, is not to fully explain Git; but, only provide a short introduction on how it works to get you started working with Xfce's development workflow. You can find the clone URL in the summary page of each repository in the Git browser.

In the example below, we do some tasks in the xfwm4 repository.

# Make a local clone of the upstream repository
git clone https://gitlab.xfce.org/xfce/xfwm4.git
 
# To keep the local copy updated with upstream you can run this from time to time
# Possibly append --rebase to fetch upstream changes and apply you modifications on
# top of those, instead of trying to merge them
git pull
 
# If you made some small modifications in the code you can view them in a unified patch
git diff
git status

In order to propose your changes you can fork the repository in question and then push your code to it and propose it via a merge request to the maintainers.

What ever you do, keep commits clean:

• Make incremental, atomic changes (one aspect at a time).
• Keep code working after every commit.
• Comment the code you write.
• Write commit messages using the standard Git message format.
• Don't fear the rebase (against the Xfce master branch): you should fix the merge problems, not the developer.
• Read the guidelines below

Back To Top

• The commit message is made of summary (first line), one empty line and the remaining lines are its description.
• Keep the summary short, aim for up to 72 characters.
• You're encouraged to write an extensive description when it makes sense, example
• Add reference to the related issue or merge request at the end of summary.
  • Reference for an issue: “Shorten strings in Arrange Items submenu (#247)”
  • Reference for a merge request: “Add new app icon (!11)”
  • When a commit relates to an issue and a merge request, only add the former to the summary and mention the latter in the description.
• Optionally Sign Off your commits (mandatory for Xfwm4!).
• GitLab's closing patterns such as fixes and closes should go into the commit description, never in the summary.
• When making isolated changes, such as in a single part of the project or one of its plugins, please add a lowercase label as the summary prefix, examples:
  • “mime-helpers: Rename Thunar to thunar”
  • “action buttons: Fix separator width”
  • “tasklist: Allow keyboard navigation within groups (#270)”

Back To Top

If you want to contribute code, the best way is to get a contributor's account and fork the project you would like to contribute to and file a merge request.

1. Ask for fork permissions on the mailing list or in our Matrix channel
2. Fork the project via the GitLab UI
3. Clone your fork locally
4. Create a new branch (try to use a descriptive name), don't use “master” (otherwise we cannot rebase and merge your branch)
5. Change and push your code to your fork/branch
6. Start a merge request and allow maintainers to change your branch (this means maintainers can rebase your branch on top of master using the GitLab Web UI)
7. Wait patiently

Back To Top

The following rules apply:

• You can only push fast-forward commits (upstream can not lose refs)
• Email addresses of each commit are validated
• Only annotated tags are allowed, tags cannot be deleted

Back To Top

The repository description shall be set via a Readme markdown file. See the Gitlab flavored markdown documentation for reference.

Back To Top

Back to main Xfce Development Information page