Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
contribute:dev:git:start [2014/03/06 09:46] – [Usage] nick | contribute:dev:git:start [2024/04/14 10:35] (current) – [GitLab Forks and Merge Requests] gael | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== | + | ~~NOTOC~~ |
+ | ====== | ||
- | Xfce uses GIT as distributed version control system (DCVS) for all the code contributed by developers. On this page we will explain the basics | + | * **[[start# |
+ | * **[[start# | ||
+ | * **[[start# | ||
+ | * **[[start# | ||
+ | * **[[start# | ||
+ | * **[[start# | ||
+ | * **[[start# | ||
+ | * **[[:contribute/ | ||
- | | + | ---- |
+ | |||
+ | ===== 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: | ||
+ | |||
+ | ---- | ||
+ | |||
+ | === Git resources === | ||
+ | |||
+ | | ||
+ | * [[https:// | ||
+ | * [[https:// | ||
* Use '' | * Use '' | ||
* Your favorite search engine | * Your favorite search engine | ||
- | === Detailed Sections | + | === Additional Git information related to Xfce === |
- | [[tips-and-tricks|Tips and Tricks]]\\ | + | * **[[tips-and-tricks|Tips and Tricks]]** -- Some additional functionality that is nice to know. |
- | Some additional functionality that is nice to know. | + | |
- | [[userrepos|User repositories]]\\ | + | * **[[github|GitHub mirror]]** -- What we do with the GitHub mirror of the Xfce repositories. |
- | How to create a user repositories. | + | |
- | ===== Set your credentials ===== | + | ---- |
+ | |||
+ | ===== Setting | ||
Before you even think about committing changes, you must set your name and email address to something valid in your **local** Git config: | Before you even think about committing changes, you must set your name and email address to something valid in your **local** Git config: | ||
Line 26: | Line 46: | ||
Make sure the email address is a __valid__ address, there is a hook on the server that checks the address of every new commit. | Make sure the email address is a __valid__ address, there is a hook on the server that checks the address of every new commit. | ||
- | ===== Usage ===== | + | [[|Back To Top]] |
+ | ---- | ||
- | Because the intention is not to explain | + | ===== Git usage example |
- | In the example below we do some tasks in the [[http://git.xfce.org/ | + | 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:// |
+ | |||
+ | In the example below, we do some tasks in the [[https://gitlab.xfce.org/ | ||
<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/ | + | git clone https://gitlab.xfce.org/ |
# 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 44: | Line 67: | ||
git diff | git diff | ||
git status | git status | ||
- | |||
- | # Redirect to a patch for in bugzilla (without credits and message) | ||
- | git diff > ~/ | ||
</ | </ | ||
- | In case the changes are more invasive, it is best to work in a separate branch. You can there commit all the individual modifications | + | In order to propose your changes you can **fork |
- | <file bash> | + | **What ever you do, keep commits clean:** |
- | # Create a branch to work in | + | |
- | git checkout -b my-fix-for-1234 | + | |
- | # Make changes | + | * Make incremental, |
- | git commit | + | * Keep code working after every commit. |
+ | * Comment the code you write. | ||
+ | * Write commit | ||
+ | * Don't fear the rebase (against the Xfce master branch): you should fix the merge problems, not the developer. | ||
+ | * Read the guidelines below | ||
- | # In case upstream changed a lot... | + | [[|Back To Top]] |
- | git checkout master | + | |
- | git pull # pull the latest upstream changes | + | |
- | git checkout my-fix-for-1234 # switch back to your branch | + | |
- | git rebase master | + | |
- | # Time to create the patches (that are in your branch and not in master) | ||
- | git format-patch -o ~/ | ||
- | </ | ||
- | In the output directory you should find various '' | + | ---- |
- | What ever you do, keep commits clean: | + | ===== Commit Guidelines ===== |
- | * Make incremental, | + | * The commit message is made of summary |
- | * Keep code working after every commit. | + | * Keep the summary short, aim for up to 72 characters. |
- | * Comment the code you write. | + | * You're encouraged to write an extensive description when it makes sense, [[https:// |
- | * Write commit | + | * Add reference to the related issue or merge request at the end of summary. |
- | * Don't fear the rebase | + | * Reference for an issue: " |
+ | * Reference for a merge request: "Add new app icon (!11)" | ||
+ | * When a commit | ||
+ | * Optionally Sign Off your commits | ||
+ | * GitLab' | ||
+ | * 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: | ||
+ | * " | ||
+ | * " | ||
+ | * " | ||
+ | [[|Back To Top]] | ||
- | ===== Permissions ===== | ||
- | 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. | + | ---- |
- | To list all your permissions | + | ===== GitLab Forks and Merge Requests ===== |
- | <file bash> | + | If you want to contribute code, the best way is to get a contributor' |
- | # W means you can write, R is read-only | + | - Ask for fork permissions [[/ |
- | ssh git@git.xfce.org | + | - Fork the project via the GitLab UI |
- | </ | + | - Clone your fork locally |
+ | - **Create a new branch** (try to use a descriptive name), don't use " | ||
+ | - Change and push your code to your fork/ | ||
+ | - Start a merge request and [[https:// | ||
+ | | ||
+ | |||
+ | [[|Back To Top]] | ||
+ | |||
+ | |||
+ | ---- | ||
+ | |||
+ | ===== Git rules on gitlab.xfce.org | ||
- | For non-user repositories the following rules apply as well: | + | The following rules apply: |
- | * You can only push fast-forward commits (upstream can not loose refs) | + | * You can only push fast-forward commits (upstream can not lose refs) |
* Email addresses of each commit are validated | * Email addresses of each commit are validated | ||
- | * You can only create and delete branches starting with your '' | ||
* Only annotated tags are allowed, tags cannot be deleted | * Only annotated tags are allowed, tags cannot be deleted | ||
- | ===== Repository description ===== | + | [[|Back To Top]] |
+ | ---- | ||
- | Set the '' | + | ===== Git repository description |
- | <file bash>ssh git@git.xfce.org | + | The repository description shall be set via a Readme markdown |
- | Every user with write access | + | [[|Back To Top]] |
+ | ---- | ||
+ | [[: |