mirror of
https://git.deluge-torrent.org/deluge
synced 2025-08-24 11:22:34 +00:00
Inital mkdocs for deluge
This commit is contained in:
Calum Lind
Calum Lind
parent
5f20e0aa66
commit
c911c6c532
108 changed files with 6665 additions and 0 deletions
96
docs/development/git/gitcommit.md
Normal file
96
docs/development/git/gitcommit.md
Normal file
|
|
@ -0,0 +1,96 @@
|
|||
In addition to the steps outlined by [GitTips](/gittips) we have put together a wrapper script around git-commit that can be used to commit to multiple branches. Simply save this script as git-commit somewhere on your PATH.
|
||||
|
||||
You can use it like so:
|
||||
|
||||
```sh
|
||||
$ git-commit -b some_branch -m "some commit message"
|
||||
```
|
||||
|
||||
**git-commit**
|
||||
|
||||
```python
|
||||
#!/usr/bin/python
|
||||
#
|
||||
# Copyright (C) 2010 Damien Churchill
|
||||
#
|
||||
# This program is free software; you can redistribute it and/or modify
|
||||
# it under the terms of the GNU General Public License as published by
|
||||
# the Free Software Foundation; either version 3, or (at your option)
|
||||
# any later version.
|
||||
#
|
||||
# This program is distributed in the hope that it will be useful,
|
||||
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
# GNU General Public License for more details.
|
||||
#
|
||||
# You should have received a copy of the GNU General Public License
|
||||
# along with this program. If not, write to:
|
||||
# The Free Software Foundation, Inc.,
|
||||
# 51 Franklin Street, Fifth Floor
|
||||
# Boston, MA 02110-1301, USA.
|
||||
|
||||
import sys
|
||||
import subprocess
|
||||
|
||||
GIT = '/usr/bin/git'
|
||||
GIT_BRANCH = '/usr/lib/git-core/git-branch'
|
||||
GIT_COMMIT = '/usr/lib/git-core/git-commit'
|
||||
GIT_CHECKOUT = '/usr/lib/git-core/git-checkout'
|
||||
GIT_CHERRY_PICK = '/usr/lib/git-core/git-cherry-pick'
|
||||
|
||||
if __name__ == '__main__':
|
||||
|
||||
branches = []
|
||||
git_args = []
|
||||
|
||||
args = sys.argv[1:]
|
||||
|
||||
while args:
|
||||
arg = args.pop(0)
|
||||
if arg in ('-b', '--branch'):
|
||||
branches.append(args.pop(0))
|
||||
elif arg.startswith('--branch='):
|
||||
branches.append(arg[9:])
|
||||
else:
|
||||
git_args.append(arg)
|
||||
|
||||
# Find out the current branch
|
||||
current_branch = None
|
||||
local_branches = []
|
||||
p = subprocess.Popen([GIT_BRANCH], stdout=subprocess.PIPE)
|
||||
for line in p.stdout:
|
||||
branch = line[2:].strip()
|
||||
local_branches.append(branch)
|
||||
if line[0] != '*':
|
||||
continue
|
||||
current_branch = branch
|
||||
|
||||
# Check to make sure that the provided branches are valid
|
||||
for branch in branches:
|
||||
if branch not in local_branches:
|
||||
sys.stderr.write('invalid branch: %s\n' % branch)
|
||||
sys.exit(1)
|
||||
|
||||
# Perform the main commit
|
||||
p = subprocess.Popen([GIT_COMMIT] + git_args, stdout=subprocess.PIPE)
|
||||
if p.wait() > 0:
|
||||
sys.stdout.write(p.stdout.read())
|
||||
sys.exit(1)
|
||||
|
||||
# Get the commit tag without using regex
|
||||
try:
|
||||
commit_tag = p.stdout.readline().split(' ')[1].split(']')[0]
|
||||
except:
|
||||
sys.stderr.write('unable to read commit tag\n')
|
||||
sys.exit(1)
|
||||
|
||||
# Loop through the specified branches applying the commit to all of
|
||||
# them.
|
||||
for branch in branches:
|
||||
subprocess.call([GIT_CHECKOUT, branch])
|
||||
sys.stdout.write('Applying commit %s to %s\n' % (commit_tag, branch))
|
||||
subprocess.call([GIT_CHERRY_PICK, commit_tag], stdout=subprocess.PIPE)
|
||||
|
||||
# Switch back to the original branch
|
||||
subprocess.call([GIT_CHECKOUT, current_branch])
|
||||
```
|
||||
91
docs/development/git/gitrepo.md
Normal file
91
docs/development/git/gitrepo.md
Normal file
|
|
@ -0,0 +1,91 @@
|
|||
# Git Source Code Repository
|
||||
|
||||
Deluge's source code is always available through our [Git repository](http://git.deluge-torrent.org/deluge).
|
||||
|
||||
To get a copy of the code, you will need to clone it from the repository then see the [['Installing/Source']].
|
||||
|
||||
For more in-depth git usage see [GitTips](/gittips).
|
||||
|
||||
This guide uses commands which are meant to be typed at a command prompt, but most will be available from a GUI Git client.
|
||||
|
||||
[Install Git](http://git-scm.com/downloads)
|
||||
|
||||
|
||||
|
||||
## Deluge Branches
|
||||
There are multiple branches or tags that you can choose from which contain different stages of the Deluge code.
|
||||
|
||||
Note that we are currently transitioning to a different [git workflow](http://nvie.com/posts/a-successful-git-branching-model/) with the development of *1.4* so picking the correct branch is crucial.
|
||||
|
||||
The current branches (at time of writing) are:
|
||||
|
||||
**`1.3-stable`**::
|
||||
This is the release branch for the 1.3-series and, until 1.4 release, is the recommended stable code. This branch is only for critical bug fixes and no new feature will appear in this branch.
|
||||
**`master`**::
|
||||
***This branch is in limbo until 1.4 release*** This branch contains development code that is now continued in `develop`. When the `develop` code is considered stable, 1.4 will be released and the code will be merged back into `master` code. This mean going forward from 1.4 release this branch will be considered to be the most stable code, replacing the use of *-stable branches.
|
||||
**`develop`**::
|
||||
All development work will be put into this branch and should be considered unstable with risk of data loss and potential incompatibility with other Deluge versions.
|
||||
**`extjs4-port`**::
|
||||
A branch for porting the WebUI code from `Ext JS 3.4` to `Ext JS 4`, still requiring a lot of development work.
|
||||
|
||||
## Initial Clone
|
||||
|
||||
The first step is to clone our git repos:
|
||||
|
||||
```
|
||||
git clone git://deluge-torrent.org/deluge.git
|
||||
```
|
||||
|
||||
This will create a *deluge* directory with a copy of the repo so if you change into this directory you can start using git commands.
|
||||
|
||||
|
||||
## Select Branch
|
||||
|
||||
List the branches, including remote branches:
|
||||
|
||||
```
|
||||
git branch -a
|
||||
```
|
||||
|
||||
## Switch Branch
|
||||
|
||||
If you want to use a different branch than the default selected (`master`) then you will need to create a local copy of the remote branch. In this example we create branch '1.3-stable' as a local copy of the remote branch 'origin/1.3-stable' and switch to it:
|
||||
|
||||
```
|
||||
git checkout -b 1.3-stable origin/1.3-stable
|
||||
```
|
||||
|
||||
To switch between your local branches use the following commands:
|
||||
|
||||
**Development:**
|
||||
|
||||
```
|
||||
git checkout develop
|
||||
```
|
||||
|
||||
**Stable:**
|
||||
|
||||
```
|
||||
git checkout 1.3-stable
|
||||
```
|
||||
|
||||
## Show current Branch
|
||||
Either of these commands will show the current branch you are using:
|
||||
|
||||
```
|
||||
git branch
|
||||
git status
|
||||
```
|
||||
|
||||
|
||||
## Updating
|
||||
|
||||
You only need to do a clone once, after that you can simply update the branch by *pulling* changes from the repo.
|
||||
|
||||
Assuming you are in the folder you cloned to:
|
||||
|
||||
```
|
||||
git pull
|
||||
```
|
||||
|
||||
Now your tree is synchronized to the latest revision in our repository!
|
||||
213
docs/development/git/gittips.md
Normal file
213
docs/development/git/gittips.md
Normal file
|
|
@ -0,0 +1,213 @@
|
|||
# Git Tips
|
||||
|
||||
|
||||
This page is a collection of useful git tips.
|
||||
|
||||
## Merge a feature branch
|
||||
|
||||
In this example we assume that your feature branch, `myfeature`, is based off `develop` and that you are currently in your feature branch.
|
||||
|
||||
1. Squash/reword/edit any commits if need be
|
||||
|
||||
```sh
|
||||
git rebase -i develop
|
||||
```
|
||||
1. Rebase your feature branch on top of current develop
|
||||
|
||||
```sh
|
||||
git rebase develop
|
||||
```
|
||||
1. Change to develop
|
||||
|
||||
```sh
|
||||
git checkout develop
|
||||
```
|
||||
1. `Fast-forward` merge your feature branch into develop
|
||||
|
||||
```sh
|
||||
git merge myfeature
|
||||
```
|
||||
1. Delete your local feature branch (see above tip for remote deletion)
|
||||
|
||||
```sh
|
||||
git branch -d myfeature
|
||||
```
|
||||
|
||||
## Ignore changes in a tracked file
|
||||
|
||||
To ignore:
|
||||
|
||||
```sh
|
||||
git update-index --assume-unchanged <tracked-file>
|
||||
```
|
||||
|
||||
To stop ignoring:
|
||||
|
||||
```sh
|
||||
git update-index --no-assume-unchanged <ignored-tracked-file>
|
||||
```
|
||||
|
||||
## Undo the last commit
|
||||
*Changes are put back into staged*
|
||||
|
||||
```sh
|
||||
git reset --soft HEAD~1
|
||||
```
|
||||
|
||||
|
||||
## Delete the last commit
|
||||
*All changes are lost! *
|
||||
|
||||
```sh
|
||||
git reset --hard HEAD~1
|
||||
```
|
||||
|
||||
## Stash untracked files
|
||||
|
||||
At times you will be working on a branch with untracked files (new files) and you'll need to checkout master to apply a bug fix.
|
||||
|
||||
First, add the untracked files to the index:
|
||||
|
||||
```sh
|
||||
git add <untracked-files>
|
||||
```
|
||||
|
||||
Now do a regular stash:
|
||||
|
||||
```sh
|
||||
git stash
|
||||
```
|
||||
|
||||
At this point you can checkout whatever branch you want and do what you need to do. When you're done, checkout your original working branch again and pop the changes from your stash:
|
||||
|
||||
```sh
|
||||
git stash pop
|
||||
```
|
||||
|
||||
You can remove the files you indexed from the index if you want, as to not pollute your next commit:
|
||||
|
||||
```sh
|
||||
git rm --cached <files>
|
||||
```
|
||||
|
||||
## Merge a remote branch
|
||||
|
||||
First, add the repo:
|
||||
|
||||
```sh
|
||||
git remote add <reponame> <location>
|
||||
```
|
||||
|
||||
Now fetch in the changes:
|
||||
|
||||
```sh
|
||||
git fetch <reponame>
|
||||
```
|
||||
|
||||
You'll want to do a diff against your branch to see what will be merged:
|
||||
|
||||
```sh
|
||||
git diff master <reponame>/<branch>
|
||||
```
|
||||
|
||||
If you're happy with the changes, go ahead and merge it:
|
||||
|
||||
```sh
|
||||
git merge <reponame>/<branch>
|
||||
```
|
||||
|
||||
|
||||
## Delete a remote branch
|
||||
|
||||
```sh
|
||||
git push <repo> :<branch>
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```sh
|
||||
git push --delete <repo> <branch>
|
||||
```
|
||||
|
||||
## Apply a commit to multiple branches with cherry-pick
|
||||
|
||||
This technique uses cherry-pick to apply commits to branches that differ too much to use `merge`.
|
||||
|
||||
1. Checkout `master` branch
|
||||
|
||||
```sh
|
||||
git checkout master
|
||||
```
|
||||
1. Make commit
|
||||
|
||||
```sh
|
||||
git commit -m "Fixed the bug that caused issue xyz"
|
||||
```
|
||||
1. Checkout stable branch
|
||||
|
||||
```sh
|
||||
git checkout stable
|
||||
```
|
||||
1. Apply the last commit from master to this branch
|
||||
|
||||
```sh
|
||||
git cherry-pick master
|
||||
```
|
||||
|
||||
## Commit Messages
|
||||
|
||||
```comment
|
||||
This should probably have it's own page but putting here for now.
|
||||
```
|
||||
Based on [git commit guidelines](http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines) and [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/).
|
||||
|
||||
The short answer on the golden rule for git commit subject lines is to you ask yourself:
|
||||
**If applied, this commit will...** *<your commit subject line here>*
|
||||
|
||||
|
||||
e.g. If applied, this commit will `Enable editing of torrent names in Add Dialog`
|
||||
|
||||
A general guideline on writing a good commit message is to provide information
|
||||
that is not already provided from the commit diff, which in essence is "*the why, not the how*".
|
||||
|
||||
* Explain why the change is necessary
|
||||
* *After reading the commit message it should should be apparent why the changes were made.*
|
||||
|
||||
* Explain how the issue is addressed in broad terms
|
||||
* *It is not necessary to explain how the changes are made in detail as that can be seen from the commit diff.*
|
||||
|
||||
Example commit message:
|
||||
|
||||
```
|
||||
Short summary of changes (preferably 50 characters or less)
|
||||
|
||||
More detailed explanatory text, if necessary. Wrap it to about 72
|
||||
characters or so. The first line can be considered as the subject of an
|
||||
email and the rest of the text as the body. The blank line separating
|
||||
the summary from the body is critical, unless you omit the body entirely.
|
||||
|
||||
Further paragraphs come after blank lines.
|
||||
|
||||
- Bullet points are okay, too
|
||||
|
||||
- Typically a hyphen or asterisk is used for the bullet, preceded by a
|
||||
single space, with blank lines in between, but conventions vary here
|
||||
```
|
||||
|
||||
### Tags / Labels
|
||||
To differentiate commit changes at a glance, the subject of commits for specific components should be prefixed with relevant tags/labels, such as:
|
||||
*Core*, *WebUI*, *GTKUI*, *Tests*, *Packaging*, *Console*, *Blocklist*, *Lint* etc. (see git logs for more examples)
|
||||
|
||||
`[GTKUI] Enable editing of torrent names in Add Dialog`
|
||||
|
||||
If the commit fix/closes a ticket, include the number:
|
||||
|
||||
`[[#1001](/ticket/1001)] Add support for magnet uris`
|
||||
|
||||
A limited number of tags may be combined, such as
|
||||
|
||||
`[[#1002](/ticket/1002)] [GTKUI] Fix the files tab context menu not being displayed`
|
||||
|
||||
`[[#2250](/ticket/2250)] [Core] [GTKUI] Add method remove_torrents to core`
|
||||
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue