Xfce Wiki

Sub domains
 

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
contribute:dev:git:start [2019/09/08 02:56] – [Using Git within the Xfce development workflow] kevinbowencontribute:dev:git:start [2024/04/14 10:35] (current) – [GitLab Forks and Merge Requests] gael
Line 1: Line 1:
 +~~NOTOC~~
 ====== Using Git within the Xfce development workflow ====== ====== Using Git within the Xfce development workflow ======
  
   * **[[start#Introduction|Introduction]]**   * **[[start#Introduction|Introduction]]**
   * **[[start#Setting your Git credentials|Setting your Git credentials]]**   * **[[start#Setting your Git credentials|Setting your Git credentials]]**
-  * **[[start#Git usage example on an Xfce project|Git usage example on an Xfce project]]** +  * **[[start#Git usage example on an Xfce project|Git usage example on an Xfce project]]**  
-  * **[[start#Git permission on git.xfce.org|Git permission on git.xfce.org]]**+  * **[[start#Commit Guidelines|Commit Guidelines]]** 
 +  * **[[start#GitLab Forks and Merge Requests|GitLab Forks and Merge Requests]]** 
 +  * **[[start#Git rules on gitlab.xfce.org|Git rules on gitlab.xfce.org]]**
   * **[[start#Git repository description|Git repository description]]**   * **[[start#Git repository description|Git repository description]]**
-  * **[[https://docs.xfce.org/contribute/dev/git/github|Xfce GitHub mirror]]+  * **[[:contribute/dev/git/github|Xfce GitHub mirror]]** 
 + 
 +----
  
 ===== Introduction ===== ===== Introduction =====
  
 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: 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:
 +
 +----
  
 === Git resources === === Git resources ===
Line 23: Line 30:
  
   * **[[tips-and-tricks|Tips and Tricks]]** -- Some additional functionality that is nice to know.   * **[[tips-and-tricks|Tips and Tricks]]** -- Some additional functionality that is nice to know.
- 
-  * **[[userrepos|Xfce user repositories]]** -- How to create a user repository on [[https://git.xfce.org]]. 
  
   * **[[github|GitHub mirror]]** -- What we do with the GitHub mirror of the Xfce repositories.   * **[[github|GitHub mirror]]** -- What we do with the GitHub mirror of the Xfce repositories.
 +
 +----
  
 ===== Setting your Git credentials ===== ===== Setting your Git credentials =====
Line 41: Line 48:
 [[|Back To Top]] [[|Back To Top]]
 ---- ----
 +
 ===== Git usage example on an Xfce project ===== ===== Git usage example on an Xfce project =====
  
-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 [[http://git.xfce.org|Git browser]].+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 [[https://gitlab.xfce.org|Git browser]].
  
-In the example below, we do some tasks in the [[http://git.xfce.org/xfce/xfwm4/|xfwm4]] repository.+In the example below, we do some tasks in the [[https://gitlab.xfce.org/xfce/xfwm4/|xfwm4]] repository.
  
 <file bash> <file bash>
 # Make a local clone of the upstream repository # Make a local clone of the upstream repository
-git clone git://git.xfce.org/xfce/xfwm4+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 # To keep the local copy updated with upstream you can run this from time to time
Line 59: Line 67:
 git diff git diff
 git status git status
- 
-# Redirect to a patch for in bugzilla (without credits and message) 
-git diff > ~/fix-for-bug-1234.patch  
 </file> </file>
  
-In case the changes are more invasive, it is best to work in a separate branch. You can there commit all the individual modifications and when finished create a patch bundle. +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.
- +
-<file bash> +
-# Create a branch to work in +
-git checkout -b my-fix-for-1234 +
- +
-# Make changes and commit them +
-git commit +
- +
-# In case upstream changed a lot... +
-git checkout master          # switch back to the master branch +
-git pull                     # pull the latest upstream changes +
-git checkout my-fix-for-1234 # switch back to your branch +
-git rebase master            # rebase your branch on top of the updated master +
- +
-# Time to create the patches (that are in your branch and not in master) +
-git format-patch -o ~/output/directory/ --signoff master+
  
-# If you have multiple (e.g. 5) patches, put them in a single file like that: +**What ever you do, keep commits clean:**
-git format-patch -5 --stdout > multi_commit.patch +
- +
-</file> +
- +
-In the output directory you should find various ''0001-message.patch'' files. Those are suitable to attach in a bug in the [[https://bugzilla.xfce.org|bug tracker]]. +
- +
-What ever you do, keep commits clean:+
  
   * Make incremental, atomic changes (one aspect at a time).   * Make incremental, atomic changes (one aspect at a time).
Line 96: Line 78:
   * Write commit messages using the standard Git message format.   * 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.   * 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]] [[|Back To Top]]
 +
  
 ---- ----
-===== Git permission on git.xfce.org ===== 
  
-<note tip>These apply if you have a [[contribute:dev:get-a-contributor-account|contributor account]]</note>+===== Commit Guidelines =====
  
-There are a number of rules we enforce in the upstream repositories. If you are experimenting with code (and thus working with more branches and rebasing) it is therefore advised to do this in a [[userrepos|user repository]] and wait with the merge upstream when everything is ready.+  * 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, [[https://gitlab.xfce.org/xfce/xfwm4/-/commit/49c1a33a4dfe15f312334584c22b4ec3ed792214|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 [[https://docs.gitlab.com/ce/user/project/issues/managing_issues.html#default-closing-pattern|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)"
  
-To list all your permissions and repositories you can access to, run the following command:+[[|Back To Top]]
  
-<file bash> 
-# W means you can write, R is read-only 
-ssh git@git.xfce.org info 
-</file> 
  
-For non-user repositories the following rules apply as well:+----
  
-  * You can only push fast-forward commits (upstream can not loose refs) +===== GitLab Forks and Merge Requests ===== 
-  * Email addresses of each commit are validated + 
-  * You can only create and delete branches starting with your ''$sshname'' +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 [[https://gitlab.xfce.org/help/user/project/merge_requests/index.md|merge request]]. 
-  * Only annotated tags are allowed, tags cannot be deleted+  - Ask for fork permissions [[/contribute/start#communication|on the mailing list or in our Matrix channel]] 
 +  - Fork the project via the GitLab UI 
 +  - Clone your fork locally 
 +  - **Create a new branch** (try to use a descriptive name), don't use "master" (otherwise we cannot rebase and merge your branch) 
 +  - Change and push your code to your fork/branch 
 +  - Start a merge request and [[https://docs.gitlab.com/ee/user/project/merge_requests/allow_collaboration.html|allow maintainers to change your branch]] (this means maintainers can rebase your branch on top of master using the GitLab Web UI) 
 +  - Wait patiently
  
 [[|Back To Top]] [[|Back To Top]]
 +
 +
 ---- ----
-===== Git repository description ===== 
  
-Set the ''description'' file contents at the remote repository. The description is used in the [[http://git.xfce.org|web interface]].+===== Git rules on gitlab.xfce.org =====
  
-<file bash>ssh git@git.xfce.org desc users/$user/$name "Your single-line repository description for cgit"</file>+The following rules apply:
  
-Every user with write access to the repository can change the description. The CGit interface is updated with a cronjob, so it might take up to 15 minutes before the new description is visible.+  * 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]] [[|Back To Top]]
 ---- ----
-===== Adding and removing private keys ===== 
  
-TODO SSKM+===== Git repository description ===== 
 + 
 +The repository description shall be set via a Readme markdown file. See the [[https://gitlab.xfce.org/help/user/markdown|Gitlab flavored markdown documentation]] for reference. 
 + 
 +[[|Back To Top]] 
 +---- 
 +[[:contribute:dev:start:|Back to main Xfce Development Information page]]