KDE TechBase - User contributions [en]

Development/Git

2012-10-30T14:56:41Z

Odysseus:

<languages />
<translate>

This is the hub page for all information about the use of Git by KDE.

== KDE and Git == 


This section provides details on using the KDE Git infrastructure. This is intended for use by KDE developers to find out how KDE uses Git and how to set up Git for use with KDE.


The [http://community.kde.org/Sysadmin/GitKdeOrgManual KDE Git System Administrators Manual] is a useful resource for more details on the technical implementation of the KDE Git infrastructure.


For more information on how the KDE Git Repositories are organized, please see the [[Getting_Started/Sources|Sources]] page or the [https://projects.kde.org/projects KDE Git Projects] page.


Please note that some KDE modules are still using SVN, for more details read the [[Getting_Started/Sources/Using_Subversion_with_KDE|Using Subversion with KDE]] page.

=== KDE Git Configuration === 


How to configure Git for use with the KDE infrastructure.


Please see the [[Special:myLanguage/Development/Git/Configuration|Git Configuration page]].

=== KDE Git Policies === 


KDE policies on Git. More generic development policies go elsewhere.

No formal workflow policy currently exists, but a number of draft proposals have been made:
* [[Development/Git/Simple_Workflow]]
* [[Development/Git/Feature_Branch_Workflow]]
* [[Development/Tutorials/Git/Feature_Development_Workflow]]
* http://community.kde.org/Frameworks/Git_Workflow

The SVN Commit Policy is being reviewed to be replaced with a new Commit Policy applying to both SVN and Git:
* [[Policies/SVN_Commit_Policy]]
* [[Policies/Draft/Commit_Policy]]

=== KDE Git Recipes === 


Short recipes for using Git with the KDE infrastructure.


Please see the [[Special:myLanguage/Development/Git/Recipes|Git Recipes page]].

=== KDE Git Tutorials === 


More in-depth instructions in using Git.


* [[Special:myLanguage/Development/Tutorials/Git/GitQuickStart|A quick step-by-step guide for getting started]]


* [[Special:myLanguage/Development/Tutorials/Git/Create a patch|Creating a patch]]


Please help filling this section by
* checking the links at the bottom of the page and see which still have valid content
* write tutorials yourself

== External Git Resources == 


Links to useful external sites about Git

=== Official Documentation === 


* [http://git-scm.com/documentation Links to git official documentation]

=== Git for SVN Users === 


* [http://git-scm.com/course/svn.html The git-svn Crash Course]

=== Git books === 


* [http://progit.org/book/ Pro Git] - An easy to understand book on git (CC licensed).


* [http://book.git-scm.com/ The git community book], also as a [http://book.git-scm.com/book.pdf pdf]

=== Tutorials === 


* [http://www-cs-students.stanford.edu/~blynn/gitmagic/ Git Magic] - A good intro to git (in several languages!)


*[http://tom.preston-werner.com/2009/05/19/the-git-parable.html The Git Parable]
- Essential reading if you want to truly understand git.


* [http://www.gitcasts.com/ Git Screencasts]

=== Cheat Sheets === 


* [http://cheat.errtheblog.com/s/git Quick reference]


* [http://zrusin.blogspot.com/2007/09/git-cheat-sheet.html Illustrated git cheat sheet]
(broken image, get it from [[Media:Zrusin-git-cheat-sheet-medium.png]])

= Documentation Changes = 

== KDE Documentation Review == 

=== Existing Pages For Review === 


Existing KDE pages about Git, SVN, and/or buildinga KDE that need to be revised. When revising pages try to split the generic development and revision control policies separate from Git specific stuff. Do not refer to "the KDE Git Repository" but instead the "KDE Code Repository". Lots of small simple pages that are less daunting to newbies and can be linked to from multiple locations are preferred to massive walls of text.


Keep:


* [[Special:myLanguage/Development/Tutorials/Git/Basics|Basics]]


* [[Special:myLanguage/Development/Tutorials/Git/git-svn|Git-svn]]


* [[Special:myLanguage/Development/Tutorials/Git/kde-qt| Kde-qt]]


* [[Special:myLanguage/Getting Started/Sources/Amarok Git Tutorial| The Amarok Git Tutorial]]


On community.kde.org:


* [http://community.kde.org/Sysadmin/GitKdeOrgManual Git-KDE Manual]


* [http://community.kde.org/20110213_GitWorkflowAgenda Git Workflow Agenda]


* [http://community.kde.org/20110213_GitWorkflowAgenda/StevesIdea Git Workflow Agenda, Steve's Idea]


On techbase.kde.org:


* [[Special:myLanguage/Getting Started|Getting Started]]


* [[Special:myLanguage/Getting Started/Build/KDE4| Build KDE 4]]


* [[Special:myLanguage/Getting Started/Build/KDE4.x|Build KDE 4.x]]


* [[Special:myLanguage/Getting Started/Build/KDE4/Prerequisites|Prerequisites]]


* [[Special:myLanguage/Getting Started/Build/KDE4/Windows/subversion|Subversion on Windows]]


* [[Special:myLanguage/Getting_Started/Increased_Productivity_in_KDE4_with_Scripts|Increase Productivity with Scripts]]


* [[Special:myLanguage/Getting_Started/Build/kdesrc-build|Kdesrc-build]]


* [[Special:myLanguage/Getting Started/Sources/Anonymous SVN|Anonymous SVN]]


* [[Special:myLanguage/Getting_Started/Sources/Using_Subversion_with_KDE|Subversion with KDE]]


* [[Special:myLanguage/Getting_Started/Using_an_IDE_with_KDE4|Using an IDE with KDE 4]]


* [[Special:myLanguage/Policies/SVN_Commit_Policy|SVN Commit Policy]]


* [[Special:myLanguage/Policies/SVN_Guidelines|SVN Guidelines]]


* [[Special:myLanguage/Development/Tools|Development Tools]]


* [[Special:myLanguage/Development/Tutorials/Git/Recipes|Git Recipes]]


* [[Special:myLanguage/Development/Tutorials/Git/decoding-git|Decoding Git]]


* [[Special:myLanguage/Projects/rekonq/Git_with_rekonq_HowTo|Git with Rekonq How-to]]


* [[Special:myLanguage/Projects/Related/Subversion|Subversion]]


* [[Special:myLanguage/Projects/MovetoGit|Move to Git]]


* [[Special:myLanguage/Projects/MoveToGit/StepsToMove|Steps to Move]]


* [[Special:myLanguage/Contribute/Get a SVN Account|Get a SVN Account]]


* [[Special:myLanguage/Contribute/First Steps with your KDE SVN Account|First Steps with your KDE SVN Account]]


There are also numerous other pages referring to "the KDE SVN/subversion repositories" which should be replaced with the generic "KDE code repositories".


There are also numerous translated pages which will need to be updated once the original pages are completed.

=== New Page Structure === 


* [[Special:myLanguage/Getting_Started|Getting Started]]


* [[Special:myLanguage/Getting_Started/Build|Getting_Started/Build]]


* [[Special:myLanguage/Getting_Started/Build/Environment|Getting_Started/Build/Environment]]


* [[Special:myLanguage/Getting_Started/Build/Requirements|Getting_Started/Build/Requirements]]


* [[Special:myLanguage/Getting_Started/Build/Qt|Getting_Started/Build/Q]]


* [[Special:myLanguage/Getting_Started/Build/KdeSupport|Getting_Started/Build/KdeSupport]]


* [[Special:myLanguage/Getting_Started/Build/Windows|Getting_Started/Build/Windows]]


* [[Special:myLanguage/Getting_Started/Build/Mac_OS_X|Getting_Started/Build/Mac_OS_X]]


* [[Special:myLanguage/Getting_Started/Run/Shell|Getting_Started/Run/Shell]]


* [[Special:myLanguage/Getting_Started/Run/Nested_Session|Getting_Started/Run/Nested_Session]]


* [[Special:myLanguage/Getting_Started/Run/Full_Session|Getting_Started/Run/Full_Session>]]
</translate>

Development/Git

2012-10-30T11:47:03Z

Odysseus:

<languages />
<translate>

This is the hub page for all information about the use of Git by KDE.

== KDE and Git == 


This section provides details on using the KDE Git infrastructure. This is intended for use by KDE developers to find out how KDE uses Git and how to set up Git for use with KDE.


The [http://community.kde.org/Sysadmin/GitKdeOrgManual KDE Git System Administrators Manual] is a useful resource for more details on the technical implementation of the KDE Git infrastructure.


For more information on how the KDE Git Repositories are organized, please see the [[Getting_Started/Sources|Sources]] page or the [https://projects.kde.org/projects KDE Git Projects] page.


Please note that some KDE modules are still using SVN, for more details read the [[Getting_Started/Sources/Using_Subversion_with_KDE|Using Subversion with KDE]] page.

=== KDE Git Configuration === 


How to configure Git for use with the KDE infrastructure.


Please see the [[Special:myLanguage/Development/Git/Configuration|Git Configuration page]].

=== KDE Git Policies === 


KDE policies on Git. More generic development policies go elsewhere.

No formal workflow policy currently exists, but a number of draft proposals have been made:
* [[Development/Git/Simple_Workflow]]
* [[Development/Git/Feature_Branch_Workflow]]
* [[Development/Tutorials/Git/Feature_Development_Workflow]]
* http://community.kde.org/Frameworks/Git_Workflow

=== KDE Git Recipes === 


Short recipes for using Git with the KDE infrastructure.


Please see the [[Special:myLanguage/Development/Git/Recipes|Git Recipes page]].

=== KDE Git Tutorials === 


More in-depth instructions in using Git.


* [[Special:myLanguage/Development/Tutorials/Git/GitQuickStart|A quick step-by-step guide for getting started]]


* [[Special:myLanguage/Development/Tutorials/Git/Create a patch|Creating a patch]]


Please help filling this section by
* checking the links at the bottom of the page and see which still have valid content
* write tutorials yourself

== External Git Resources == 


Links to useful external sites about Git

=== Official Documentation === 


* [http://git-scm.com/documentation Links to git official documentation]

=== Git for SVN Users === 


* [http://git-scm.com/course/svn.html The git-svn Crash Course]

=== Git books === 


* [http://progit.org/book/ Pro Git] - An easy to understand book on git (CC licensed).


* [http://book.git-scm.com/ The git community book], also as a [http://book.git-scm.com/book.pdf pdf]

=== Tutorials === 


* [http://www-cs-students.stanford.edu/~blynn/gitmagic/ Git Magic] - A good intro to git (in several languages!)


*[http://tom.preston-werner.com/2009/05/19/the-git-parable.html The Git Parable]
- Essential reading if you want to truly understand git.


* [http://www.gitcasts.com/ Git Screencasts]

=== Cheat Sheets === 


* [http://cheat.errtheblog.com/s/git Quick reference]


* [http://zrusin.blogspot.com/2007/09/git-cheat-sheet.html Illustrated git cheat sheet]
(broken image, get it from [[Media:Zrusin-git-cheat-sheet-medium.png]])

= Documentation Changes = 

== KDE Documentation Review == 

=== Existing Pages For Review === 


Existing KDE pages about Git, SVN, and/or buildinga KDE that need to be revised. When revising pages try to split the generic development and revision control policies separate from Git specific stuff. Do not refer to "the KDE Git Repository" but instead the "KDE Code Repository". Lots of small simple pages that are less daunting to newbies and can be linked to from multiple locations are preferred to massive walls of text.


Keep:


* [[Special:myLanguage/Development/Tutorials/Git/Basics|Basics]]


* [[Special:myLanguage/Development/Tutorials/Git/git-svn|Git-svn]]


* [[Special:myLanguage/Development/Tutorials/Git/kde-qt| Kde-qt]]


* [[Special:myLanguage/Getting Started/Sources/Amarok Git Tutorial| The Amarok Git Tutorial]]


On community.kde.org:


* [http://community.kde.org/Sysadmin/GitKdeOrgManual Git-KDE Manual]


* [http://community.kde.org/20110213_GitWorkflowAgenda Git Workflow Agenda]


* [http://community.kde.org/20110213_GitWorkflowAgenda/StevesIdea Git Workflow Agenda, Steve's Idea]


On techbase.kde.org:


* [[Special:myLanguage/Getting Started|Getting Started]]


* [[Special:myLanguage/Getting Started/Build/KDE4| Build KDE 4]]


* [[Special:myLanguage/Getting Started/Build/KDE4.x|Build KDE 4.x]]


* [[Special:myLanguage/Getting Started/Build/KDE4/Prerequisites|Prerequisites]]


* [[Special:myLanguage/Getting Started/Build/KDE4/Windows/subversion|Subversion on Windows]]


* [[Special:myLanguage/Getting_Started/Increased_Productivity_in_KDE4_with_Scripts|Increase Productivity with Scripts]]


* [[Special:myLanguage/Getting_Started/Build/kdesrc-build|Kdesrc-build]]


* [[Special:myLanguage/Getting Started/Sources/Anonymous SVN|Anonymous SVN]]


* [[Special:myLanguage/Getting_Started/Sources/Using_Subversion_with_KDE|Subversion with KDE]]


* [[Special:myLanguage/Getting_Started/Using_an_IDE_with_KDE4|Using an IDE with KDE 4]]


* [[Special:myLanguage/Policies/SVN_Commit_Policy|SVN Commit Policy]]


* [[Special:myLanguage/Policies/SVN_Guidelines|SVN Guidelines]]


* [[Special:myLanguage/Development/Tools|Development Tools]]


* [[Special:myLanguage/Development/Tutorials/Git/Recipes|Git Recipes]]


* [[Special:myLanguage/Development/Tutorials/Git/decoding-git|Decoding Git]]


* [[Special:myLanguage/Projects/rekonq/Git_with_rekonq_HowTo|Git with Rekonq How-to]]


* [[Special:myLanguage/Projects/Related/Subversion|Subversion]]


* [[Special:myLanguage/Projects/MovetoGit|Move to Git]]


* [[Special:myLanguage/Projects/MoveToGit/StepsToMove|Steps to Move]]


* [[Special:myLanguage/Contribute/Get a SVN Account|Get a SVN Account]]


* [[Special:myLanguage/Contribute/First Steps with your KDE SVN Account|First Steps with your KDE SVN Account]]


There are also numerous other pages referring to "the KDE SVN/subversion repositories" which should be replaced with the generic "KDE code repositories".


There are also numerous translated pages which will need to be updated once the original pages are completed.

=== New Page Structure === 


* [[Special:myLanguage/Getting_Started|Getting Started]]


* [[Special:myLanguage/Getting_Started/Build|Getting_Started/Build]]


* [[Special:myLanguage/Getting_Started/Build/Environment|Getting_Started/Build/Environment]]


* [[Special:myLanguage/Getting_Started/Build/Requirements|Getting_Started/Build/Requirements]]


* [[Special:myLanguage/Getting_Started/Build/Qt|Getting_Started/Build/Q]]


* [[Special:myLanguage/Getting_Started/Build/KdeSupport|Getting_Started/Build/KdeSupport]]


* [[Special:myLanguage/Getting_Started/Build/Windows|Getting_Started/Build/Windows]]


* [[Special:myLanguage/Getting_Started/Build/Mac_OS_X|Getting_Started/Build/Mac_OS_X]]


* [[Special:myLanguage/Getting_Started/Run/Shell|Getting_Started/Run/Shell]]


* [[Special:myLanguage/Getting_Started/Run/Nested_Session|Getting_Started/Run/Nested_Session]]


* [[Special:myLanguage/Getting_Started/Run/Full_Session|Getting_Started/Run/Full_Session>]]
</translate>

Development/Git

2012-10-30T11:41:50Z

Odysseus:

<languages />
<translate>

This is the hub page for all information about the use of Git by KDE.

== KDE and Git == 


This section provides details on using the KDE Git infrastructure. This is intended for use by KDE developers to find out how KDE uses Git and how to set up Git for use with KDE.


The [http://community.kde.org/Sysadmin/GitKdeOrgManual KDE Git System Administrators Manual] is a useful resource for more details on the technical implementation of the KDE Git infrastructure.


For more information on how the KDE Git Repositories are organized, please see the [[Getting_Started/Sources|Sources]] page or the [https://projects.kde.org/projects KDE Git Projects] page.


Please note that some KDE modules are still using SVN, for more details read the [[Getting_Started/Sources/Using_Subversion_with_KDE|Using Subversion with KDE]] page.

=== KDE Git Configuration === 


How to configure Git for use with the KDE infrastructure.


Please see the [[Special:myLanguage/Development/Git/Configuration|Git Configuration page]].

=== KDE Git Policies === 


KDE policies on Git. More generic development policies go elsewhere.

No formal workflow policy currently exists, but a number of draft proposals have been made:
* [[Development/Git/Simple_Workflow]]
* [[Development/Git/Feature_Branch_Workflow]]

=== KDE Git Recipes === 


Short recipes for using Git with the KDE infrastructure.


Please see the [[Special:myLanguage/Development/Git/Recipes|Git Recipes page]].

=== KDE Git Tutorials === 


More in-depth instructions in using Git.


* [[Special:myLanguage/Development/Tutorials/Git/GitQuickStart|A quick step-by-step guide for getting started]]


* [[Special:myLanguage/Development/Tutorials/Git/Create a patch|Creating a patch]]


Please help filling this section by
* checking the links at the bottom of the page and see which still have valid content
* write tutorials yourself

== External Git Resources == 


Links to useful external sites about Git

=== Official Documentation === 


* [http://git-scm.com/documentation Links to git official documentation]

=== Git for SVN Users === 


* [http://git-scm.com/course/svn.html The git-svn Crash Course]

=== Git books === 


* [http://progit.org/book/ Pro Git] - An easy to understand book on git (CC licensed).


* [http://book.git-scm.com/ The git community book], also as a [http://book.git-scm.com/book.pdf pdf]

=== Tutorials === 


* [http://www-cs-students.stanford.edu/~blynn/gitmagic/ Git Magic] - A good intro to git (in several languages!)


*[http://tom.preston-werner.com/2009/05/19/the-git-parable.html The Git Parable]
- Essential reading if you want to truly understand git.


* [http://www.gitcasts.com/ Git Screencasts]

=== Cheat Sheets === 


* [http://cheat.errtheblog.com/s/git Quick reference]


* [http://zrusin.blogspot.com/2007/09/git-cheat-sheet.html Illustrated git cheat sheet]
(broken image, get it from [[Media:Zrusin-git-cheat-sheet-medium.png]])

= Documentation Changes = 

== KDE Documentation Review == 

=== Existing Pages For Review === 


Existing KDE pages about Git, SVN, and/or buildinga KDE that need to be revised. When revising pages try to split the generic development and revision control policies separate from Git specific stuff. Do not refer to "the KDE Git Repository" but instead the "KDE Code Repository". Lots of small simple pages that are less daunting to newbies and can be linked to from multiple locations are preferred to massive walls of text.


Keep:


* [[Special:myLanguage/Development/Tutorials/Git/Basics|Basics]]


* [[Special:myLanguage/Development/Tutorials/Git/git-svn|Git-svn]]


* [[Special:myLanguage/Development/Tutorials/Git/kde-qt| Kde-qt]]


* [[Special:myLanguage/Getting Started/Sources/Amarok Git Tutorial| The Amarok Git Tutorial]]


On community.kde.org:


* [http://community.kde.org/Sysadmin/GitKdeOrgManual Git-KDE Manual]


* [http://community.kde.org/20110213_GitWorkflowAgenda Git Workflow Agenda]


* [http://community.kde.org/20110213_GitWorkflowAgenda/StevesIdea Git Workflow Agenda, Steve's Idea]


On techbase.kde.org:


* [[Special:myLanguage/Getting Started|Getting Started]]


* [[Special:myLanguage/Getting Started/Build/KDE4| Build KDE 4]]


* [[Special:myLanguage/Getting Started/Build/KDE4.x|Build KDE 4.x]]


* [[Special:myLanguage/Getting Started/Build/KDE4/Prerequisites|Prerequisites]]


* [[Special:myLanguage/Getting Started/Build/KDE4/Windows/subversion|Subversion on Windows]]


* [[Special:myLanguage/Getting_Started/Increased_Productivity_in_KDE4_with_Scripts|Increase Productivity with Scripts]]


* [[Special:myLanguage/Getting_Started/Build/kdesrc-build|Kdesrc-build]]


* [[Special:myLanguage/Getting Started/Sources/Anonymous SVN|Anonymous SVN]]


* [[Special:myLanguage/Getting_Started/Sources/Using_Subversion_with_KDE|Subversion with KDE]]


* [[Special:myLanguage/Getting_Started/Using_an_IDE_with_KDE4|Using an IDE with KDE 4]]


* [[Special:myLanguage/Policies/SVN_Commit_Policy|SVN Commit Policy]]


* [[Special:myLanguage/Policies/SVN_Guidelines|SVN Guidelines]]


* [[Special:myLanguage/Development/Tools|Development Tools]]


* [[Special:myLanguage/Development/Tutorials/Git/Recipes|Git Recipes]]


* [[Special:myLanguage/Development/Tutorials/Git/decoding-git|Decoding Git]]


* [[Special:myLanguage/Projects/rekonq/Git_with_rekonq_HowTo|Git with Rekonq How-to]]


* [[Special:myLanguage/Projects/Related/Subversion|Subversion]]


* [[Special:myLanguage/Projects/MovetoGit|Move to Git]]


* [[Special:myLanguage/Projects/MoveToGit/StepsToMove|Steps to Move]]


* [[Special:myLanguage/Contribute/Get a SVN Account|Get a SVN Account]]


* [[Special:myLanguage/Contribute/First Steps with your KDE SVN Account|First Steps with your KDE SVN Account]]


There are also numerous other pages referring to "the KDE SVN/subversion repositories" which should be replaced with the generic "KDE code repositories".


There are also numerous translated pages which will need to be updated once the original pages are completed.

=== New Page Structure === 


* [[Special:myLanguage/Getting_Started|Getting Started]]


* [[Special:myLanguage/Getting_Started/Build|Getting_Started/Build]]


* [[Special:myLanguage/Getting_Started/Build/Environment|Getting_Started/Build/Environment]]


* [[Special:myLanguage/Getting_Started/Build/Requirements|Getting_Started/Build/Requirements]]


* [[Special:myLanguage/Getting_Started/Build/Qt|Getting_Started/Build/Q]]


* [[Special:myLanguage/Getting_Started/Build/KdeSupport|Getting_Started/Build/KdeSupport]]


* [[Special:myLanguage/Getting_Started/Build/Windows|Getting_Started/Build/Windows]]


* [[Special:myLanguage/Getting_Started/Build/Mac_OS_X|Getting_Started/Build/Mac_OS_X]]


* [[Special:myLanguage/Getting_Started/Run/Shell|Getting_Started/Run/Shell]]


* [[Special:myLanguage/Getting_Started/Run/Nested_Session|Getting_Started/Run/Nested_Session]]


* [[Special:myLanguage/Getting_Started/Run/Full_Session|Getting_Started/Run/Full_Session>]]
</translate>

Projects/Marble

2012-09-19T20:50:39Z

Odysseus: /* Mapping Coordination */

[[Image:Marble_logo.png]]

== About Marble ==
;[[/Devices_and_Use_Cases|Devices and Use Cases]]
;[[/FAQ|Marble FAQ]]

== Success Stories: 3rd party applications using the Marble Library==
;[[/MarbleUsedBy|Software that makes use of Marble]]

== Tutorials: How to use the Marble Widget in your application ==
;[[/MarbleDesigner|with Qt Designer]]
;[[/MarbleWindows|On Windows, with Qt Creator/Qt Designer]]

=== With C++ ===
;[[/MarbleCPlusPlus|Hello World]]
;[[/MarbleMarbleWidget|Changing basic map properties]]
;[[/MarbleSignalsSlots|Creating a window with controls]]
;[[/MarbleGeoPainter|Painting onto the map]]
;[[/LayerInterface|Drawing in Custom Layers]]
;[[/Routing/BasicRouting|Basic Routing]]
;[[/Runners/Search|Searching for Points of Interest]]
;[[/Runners/ReverseGeocoding|Reverse Geocoding]]
;[[/Runners/Parse|Parsing Files]]
;[[/Runners/PaintingGeoDataLineString|Painting LineString]]
;[[/Runners/DisplayGeoDataPlacemark|Displaying GeoData Documents]]

;[[/MarblePython|with Python]]

;[[/MarbleDBus|via a shell script]]

== How to become a Marble developer ("Marblehead") ==

=== So you are new to Marble development ... ===

<b>Welcome!</b>

Here you'll get all the information you need to start Marble development:

;[[/GoMarble|How to become a Marble Developer]]

== Compiling Marble ==
;[[/LinuxCompiling|Compiling on Linux]]
;[[/WindowsCompiling|Compiling on Windows]]
;[[/MaemoEnvironment|Compiling on Maemo]]
;[[/MeeGoEnvironment|Compiling on MeeGo]]
;[[/PlasmaActiveEnvironment|Compiling for Plasma Active]]
;[[/MacCompiling|Compiling on Mac OS]]
;[[/QtCreator|Setting up QtCreator for Marble Development]]

== Packaging Marble ==

;[[/NewMarbleMoldules|New Marble Modules]] (future packaging advice)

Here is some advice about how packaging is supposed to happen on the various platforms that are supported.

;[[/LinuxPackaging|Packaging for Linux]]
;[[/WindowsPackaging|Packaging for Windows]]
;[[/MaemoPackaging|Packaging for Maemo]]
;[[/MeeGoPackaging|Packaging for MeeGo]]
;[[/MacPackaging|Packaging for Mac]]

== Tools for Marble ==

Here are some tools and checks that are performed on marble code:
;[https://bugs.kde.org/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=marble&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&cmdtype=doit&order=Importance Marble Open Bugs]
;[http://reviewboard.kde.org/groups/marble/ Review Board]
;[http://api.kde.org/4.x-api/kdeedu-apidocs/marble/html/index.html API Docs (KDE Trunk)]
;[http://www.englishbreakfastnetwork.org/apidocs/apidox-kde-4.x/kdeedu-marble.html APIDOX reports]
;[http://www.englishbreakfastnetwork.org/krazy/reports/kde-4.x/kdeedu/marble/index.html Krazy reports]

== Programming Coordination ==

Here are a few links to various issues we are working on:
;[[/Gsoc2010| Gsoc Students projects 2010]]
;[[/GsocGit| Use of git(orious) for GSOC]]
;[[/TODO|TODO list]]
;[[/MaemoTODO|Maemo specific TODO list]]

;[[/GSoC2011| GSoC Students' projects 2011]]
;[http://community.kde.org/SoCiS/2011/Ideas#Marble_Virtual_Globe ESA SoCIS 2011 ideas]

;[[/GSoC2012| GSoC Students' projects 2012]]

=== Translation ===
;[[/MapTranslation|Map Translation]]
;[[/UiTranslation|UI Translation]]
;[[/GeoDataCoordinatesTranslation|GeoDataCoordinates Translation]]

=== User Interface ===
;[[/Mockups|Mockups]]
;[[/IconStatus|Icon Status]]

=== Texture Mapping ===
;[[/TextureNG|Texture Mapping]]

=== GeoData Library / KML ===
The base classes to manipulate geographic data
;[[/GeoData|GeoData Presentation]]
;[[/GeoData/GeoDataUse|Use cases for GeoData classes]]
;[http://websvn.kde.org/*checkout*/trunk/KDE/kdeedu/marble/src/lib/geodata/data/README.html GeoData API Description]
;[[/GeoData/GeoDataParsing|Parsing GeoData]]
;[[/GeoData/GeoDataWriter|Writing GeoData]]
;[[/GeoData/PointerVsImplicitShare|Pointer vs. Implicit Share]]

;[[/KMLStatus|KML Status]]
;[[/GPXStatus|GPX Status]]

Using GeoData:
;[[/Placemark|Placemarks Management]]
;[[/ModelView|Review of Model-View use in marble]]

=== Geo Graphics View ===
;[[/GeoGraphicsViewOverview|Overview of the GeoGraphicsView]]
;[[/GraphicsViewGeoParser| Interaction between GeoData and GeoGraphicsView]]

=== GeoPainter / DGML ===
;[[/GeoPainter|GeoPainter]]
;[[/Dgml|DGML]]

=== Plugin Interfaces ===
;[[/Plugins|Plugin interfaces]]

=== Marble Runner ===
;[[/CoordinateRunner|Coordinate Runner]]
;[[/OsmNameFinderRunner|OSM Runner]]
;[[/RunnerHOWTO|Runner HOWTO]]

=== Online Services ===
;[[/OnlineServices|Creating new Online Services]]
;[[/ListOfPossibleOnlineServices|List of possible Online Services]]

=== Projections ===
;[[/WinkelIii|Winkel III]]
;[[/RobinsonProjection|Robinson projection]]
[http://www.radicalcartography.net/?projectionref A little overview of map projections]

=== Tile Download ===
;[[/VectorTilingProposal|Vector Tiling Proposal]]
;[[/TileDownload|Tile Download]]

=== Documentation ===
;[[/CustomMaps|How to customize maps]]
;[[/PNTFiles|How to change the PNT files used by Marble]]
;[[/MarblesSecrets|Marble's Secrets]]
;[[/ProxyConnection|How to use the Proxy]]

=== GeoClue / GPS ===
;[[/GeoClue|GeoClue support in Marble]]

=== XDG Base Directory Specification ===
;[[/xdg|XDG Base Directory Specification]]

== Mapping Coordination ==
Possible maps we could use:
* [http://pelagios.dme.ait.ac.at/maps/greco-roman/ Tiled map of the classical world] see the [http://pelagios-project.blogspot.co.uk/2012/09/a-digital-map-of-roman-empire.html authors blog] for details
* [http://www.unearthedoutdoors.net/global_data/true_marble/download TrueMarble Global 250m images]
* [http://onearth.jpl.nasa.gov/ OnEarth NASA satellite images]
* [http://worldwindcentral.com/wiki/Add-on:ZoomIt! ZoomIt! (in parts proprietary)]
* [http://sos.noaa.gov/datasets/ NOAA Science on a Sphere]
* [http://efele.net/maps/tz/world/ Olsen Time Zone map in Shapefile format]. Public Domain. Scripted to generate from current tz file.

=== Natural Earth Vector Map ===
;[[/NaturalEarth|A proposal to use the Natural Earth vector map]]

=== Documentation ===
;[[/HistoricalMaps|How to create Historical Maps]]
;[[/CustomMaps|How to create Custom Maps]]

;[[/PalaeoMaps|Global Palaeogeography]]

== Routing ==
;[[/OnlineRoutingImplementation|Implementation of Online-Routing]]
;[[/MaemoOfflineRouting|Installation of Marble and Gosmore on Maemo]]
;[[/RoutingRoadmap|Routing Roadmap]]
;[[/RoutingInstructions|Routing Instructions]]

== valgrind ==
if you want to fix memory leaks, you can run valgrind with:

valgrind --leak-check=full --track-origins=yes --num-callers=30 marble 2>&1 | tee MARBLE_MEMCHECK

== Meetings ==
Summaries and logs of scheduled Marble meetings can be found on the following pages:
;[[/MarbleMeeting20081029|Wednesday Nov. 10th, 2008]]

;[[/MarbleMeeting20101107|Marble Weekend Sprint, Nov. 5-7]]

Projects/Marble/NaturalEarth

2012-05-01T11:33:15Z

Odysseus: /* Spatialite */

= Natural Earth =

== Introduction ==

Marble currently uses the very old and outdated MWDBII dataset for its vector base map such as national borders and coastlines and we really need to replace it with more up-to-date data. However, MWDBII has two key advantages, it is very compact in size enabling Marble to ship it by default, and the individual nodes have a zoom level value which speeds up drawing.

The current vector layer also has the disadvantage of not being able to be manipulated either programtiacally or by the user. This prevents it from being used for such things as KGeography or other educational uses where you would want to select and manipulate a geographic entity.

Improving the vector base maps would thus consist of two closely related parts:
* Improving the vector drawing code to allow interaction with the vectors, and improved performance to allow more detailed vectors to be drawn.
* Importing a new base layer dataset.

== Using NaturalEarth ==

The [http://www.naturalearthdata.com/ Natural Earth data set] is a "public domain map dataset available at 1:10m, 1:50m, and 1:110 million scales. Featuring tightly integrated vector and raster data, with Natural Earth you can make a variety of visually pleasing, well-crafted maps with cartography or GIS software." This data set seems ideal as a replacement for the MWDBII.

Advantages:
* Free / Public Domain data
* Regularly updated
* Wide variety of political and geographic features
* Available at 3 different scales: 1:10m 1:50m and 1:110m
* All feature nodes at same scale are matched
* Data attributes such as country code, population, relative magnitude, etc

Disadvantages:
* Is in Shapefile format which is space inefficient
* No per node zoom level attribute
* Different scale datasets do not match so cannot efficiently be used together for zooming

The 1:10m dataset seems ideal as the base map in Marble as it provides a higher level of detail than the current MWDBII. The 1:110m dataset seems ideal for use in a country selector widget in kdelibs. The 1:50m dataset is less detailed than the current MWDBII so may be less useful.

Using the data in the default shapefile format is not considered desirable however:
* No shapefile format support in Marble (yet), would have to rely on an external library or write our own
* Space inefficient (14Mb vs 2.6Mb for MWDBII)
* No zoom level attribute or any node level attributes which would slow drawing
* Vector level attributes are stored in .dbf format which adds complexity to implementing shapefile support

The ideal solution would seem be to convert the Natural Earth data into a more efficient file format and either calculate and store the zoom level attribute in the file or calculate it on file load. The full Natural Earth dataset would be converted, but would only ship the minimal dataset required with Marble (approx 4-5Mb?) with the remainder of the data later being downloaded via GHNS or as a separate package.

=== Vector Layer Improvements ===

The main changes required to Marble will be in the vector layer itself, removing the old PNT file vector drawing code and implementing the new dataset using the new GeoData library vector support.

Two main issues will need to be solved here
* if a new file format is needed for efficient storage
* if a zoom level attribute is needed for fast drawing, and if so where and how to implement the attribute

Some possibilities for the file format are:
* Adapt the existing PNT format used for MWDBII to have a higher degree of accuracy and add an attributes table
* Use the existing Marble serial/cache format which will be faster but the size efficiency may not be sufficient
* Use shapefile by implementing a lightweight parser without dbf support but our own simple attribute table.
* Implement full shapefile support including dbf (possibly using libshape)

The zoom level problem can be solved by either:
* Calculate a zoom level for each point during the file conversion and save it in the new file format, but this will require more storage space.
* Improve the vector drawing layer to calculate the zoom level on the fly, which would benefit all vector drawing but may be too slow.

The Douglas-Peucker algorithm may be able to be used here.

Some pros/cons to consider:

* The 1:10m country file is 6.55MB and contains 533,202 points = 12.28
bytes/point compared to the PNT which is 745KB and contains 127,246 points =
5.85 bytes/point, which would suggest the NE data in PNT format would be half
the size, so 6 MB in total. This could probably be further reduced by a light
application of Douglas-Peucker.

* The NE shapefiles have been carefully processed so shared borders and
overlapping features like rivers match exactly and other such niceties,
applying the Douglas-Peucker algorithm might affect that.

* A shapefile parser would allow users/apps to load other shapefiles.

* We would have to reconvert and check the data every time there's a new NE
release which could be a lot of effort, but an automated shp2pnt script could
prove useful to allow apps/users to display their own shapefiles in a simple
way.

* It is unknown if the D-H algorithm can be deployed in a way to mark each point with a detail level rather than just throwing the points away.

==== Calculating Zoom Level on the fly ====
Using GeoPainter and GeoDataLineString ("libgeodata"):
* Apply Douglas-Peuker dynamically in GeoDataLineString class to set Detail Level
* When GeoDataLineString modified (add/del point) set dirty flag
* When node accessed for drawing, Dirty flag would trigger D-P to calculate detail level and unset dirty flag
* Would benefit all vector formats, e.g. kml, ppx, shp

==== Possible new file format ====
Potential new Marble file format based on PNT:
* 1st integer (32 bit): Latitude in arcseconds highest bit indicates new polygon starts: header information has to be read from 3rd integer
* 2nd integer (32 bit): Longitude in arcseconds
* Optional 3rd integer: feature key highest bit feature geometry (line or ring).

Applying this to the 1:10m dataset:
* Each point takes 64 bits/8 bytes
* The start of each polygon takes 96 bits
* Roughly 533,202 x 8 bytes = 4 Mb for the country borders alone, not including internal border and coastline files
* If that's too much to ship, then ship the 1:50m dataset as the default and download the 1:10m dataset once online

==== Attribute Database ====

Metadata file:
* convert / filter dbf into our own format
* could just be csv or xml? or sqlite?

Rather than the Geonames ID, we could just use the Natural Earth object ID,
then a look-up file/table that matches the NE ID to the ISO / FIPS / whatever
code (NE provides this in the metadata) and Geonames ID (which we would have
to provide). This would allow look-ups via whatever code or ID is available,
and we wouldn't be reliant on Geonames IDs staying constant or being online.

==== Spatialite ====

One option would be to integrate Spatialite and use this as both the data storage for the vectors and as the attribute database. Spatialite is an extension to SQLite implementing a Spatial SQL database. Among the feature this provides is a compact data storage format and the ability to import Shapefiles and CSV files, as well as access all the standard GEOS tools if installed.

There is a 20Mb zip file available for Natural Earth in Spatialite format, it is unclear how much of Natural Earth is contained in this. A minimal dataset could be shipped by default with the full dataset downloaded later.

Spatial SQL queries could return just those vectors currently in the viewport, but repeated reloading and redrawing could be inefficient. However this may also solve the Level-of-Detail problem.

The major downside is the dependencies which include SQLite, PROJ and GEOS so on a platform like Windows would require a larger monolithic binary which defeats the purpose of shipping slimmed down data.

More research is required here. It may not be a suitable option for the default Atlas view, but would be a very powerful extension for Marble to provide lightweight GIS-like functionality.

=== Action Plan ===

A possible action plan is
# Fix GeoPainter LinearRings which contain a pole not rendered correctly
# Implement Douglas-Peucker reduction in GeoDataLineString
# New PNT file format definition (with a different name, MBL?)
# Metadata file format definition
# New GeoData PNT2 file loading code (convert old data).
# shp2pnt2 script to convert shp to new formats (using Perl::shp? there's shp2xxx scripts out there we could copy?), including matching to Geonames ID
# split files into 'ship with', 'download asap', 'ghns'

Later add simple shapefile loading to GeoData, maybe with attibute layer?

== Natural Earth Datasets ==

=== Dataset Sizes ===

Key Natural Earth data files from v1.2, recent updates to 1.3 not included.
<pre>
1:110m 1:50m 1:10m
------ ------- -------
Admin level 0 countries 172 KB 1.36 MB 6.55 MB
Admin level 0 land borders 39 KB 301 KB 896 KB
Admin level 0 sea borders 12 KB 40 KB 79 KB
Admin level 0 disputed 40 KB 157 KB
Admin level 1 regions 39 KB 339 MB 13.9 MB *
Admin level 1 land borders 16 KB 60 KB 4.82 MB
Coastlines 79 KB 883 KB 2.15 MB
Rivers 19 KB 420 KB 3.29 MB
Lakes 10 KB 286 KB 786 MB
Glaciers 13 KB 208 KB 1.23 MB
Dateline 18 KB 18 KB 18 KB
Playas 18 KB 106 KB
Ice Shelves 105 KB 211 KB
Minor Islands 449 KB
Reefs 171 KB
------- ------- ---------
417 KB 4.08 MB 34.03 MB

* level 1 regions are USA/Canada only at 110m and 50m, but whole world at 10m,
perfect for KGeography use :-)

Other useful files:
Physical Features Land 146 KB 1.50 MB 692 KB
Physical Features Sea 348 KB 836 KB 836 MB
Populated Places 347 KB 1.48 MB
Urban Areas 439 KB 3.48 MB
Bathmetry 11.64 MB

</pre>

=== Dataset Details ===

* Countries
** matched boundary lines and polygons with names attributes for countries and
sovereign states. Includes dependencies (French Polynesia),
map units (U.S. Pacific Island Territories) and
sub-national map subunits (Corsica versus mainland Metropolitan France).
** Core data

* Disputed areas and breakaway regions
** From Kashmir to the Elemi Triangle, Northern Cyprus to Western Sahara.
** Core data

* Internal boundaries
** Core data??

* Coastline
** ocean coastline, including major islands. Coastline is matched to land and water polygons.
** Core data?

* First order admin (provinces, departments, states, etc.)
** internal boundaries and polygons for all but a few tiny island nations. Includes names attributes and some statistical groupings of the same for smaller countries.
** Optional download

* Populated places
** point symbols with name attributes. Includes capitals, major cities and towns, plus significant smaller towns in sparsely inhabited regions. We favor regional significance over population census in determining rankings.
** Optional download, or use to replace current places file?

* Urban polygons
** derived from 2002-2003 MODIS satellite data.
** Optional download

* Pacific nation groupings
** boxes for keeping these far-flung islands tidy.
** Optional download

* Water boundary indicators
** partial selection of key 200-mile nautical limits, plus some disputed, treaty, and median lines.
** Optional download

* Land
** Land polygons including major islands
** Optional download

* Ocean
** Ocean polygon split into contiguous pieces.
** Optional download

* Minor Islands
** additional small ocean islands ranked to two levels of relative importance.
** Optional download

* Reefs
** major coral reefs from WDB2.
** Optional download

* Physical region features
** polygon and point labels of major physical features.
** Optional download

* Rivers and Lake Centerlines
** ranked by relative importance. Includes name and line width attributes. Don’t want minor lakes? Turn on their centerlines to avoid unseemly data gaps.
** Optional download

* Lakes
** Ranked by relative importance, coordinating with river ranking. Includes name attributes.
** Optional download

*Glaciated areas
** polygons derived from DCW, except for Antarctica derived from MOA. Includes name attributes for major polar glaciers.
** Optional download

*Antarctic ice shelves
** Derived from 2003-2004 MOA. Reflects recent ice shelf collapses.
** Optional download

*Bathymetry
** nested polygons at 0, -200, -1,000, -2,000, -3,000, -4,000, -5,000, -6,000, -7,000, -8,000, -9,000,and -10,000 meters. Created from SRTM Plus.
** Optional download

* Parks and protected areas
** US Only
** Don't use, maybe user download layer

* Geographic lines
** Polar circles, tropical circles, equator, and International Date Line.
** Probably not useful to Marble as we have a plugin for most of these.
** International Date Line could be extracted

*Graticules
** 1-, 5-, 10-, 15-, 20-, and 30-degree increments. Includes WGS84 bounding box.
** Probably not useful to Marble as we have a Graticle plugin.

Projects/Marble/NaturalEarth

2012-05-01T11:23:45Z

Odysseus: /* Spatialite */

= Natural Earth =

== Introduction ==

Marble currently uses the very old and outdated MWDBII dataset for its vector base map such as national borders and coastlines and we really need to replace it with more up-to-date data. However, MWDBII has two key advantages, it is very compact in size enabling Marble to ship it by default, and the individual nodes have a zoom level value which speeds up drawing.

The current vector layer also has the disadvantage of not being able to be manipulated either programtiacally or by the user. This prevents it from being used for such things as KGeography or other educational uses where you would want to select and manipulate a geographic entity.

Improving the vector base maps would thus consist of two closely related parts:
* Improving the vector drawing code to allow interaction with the vectors, and improved performance to allow more detailed vectors to be drawn.
* Importing a new base layer dataset.

== Using NaturalEarth ==

The [http://www.naturalearthdata.com/ Natural Earth data set] is a "public domain map dataset available at 1:10m, 1:50m, and 1:110 million scales. Featuring tightly integrated vector and raster data, with Natural Earth you can make a variety of visually pleasing, well-crafted maps with cartography or GIS software." This data set seems ideal as a replacement for the MWDBII.

Advantages:
* Free / Public Domain data
* Regularly updated
* Wide variety of political and geographic features
* Available at 3 different scales: 1:10m 1:50m and 1:110m
* All feature nodes at same scale are matched
* Data attributes such as country code, population, relative magnitude, etc

Disadvantages:
* Is in Shapefile format which is space inefficient
* No per node zoom level attribute
* Different scale datasets do not match so cannot efficiently be used together for zooming

The 1:10m dataset seems ideal as the base map in Marble as it provides a higher level of detail than the current MWDBII. The 1:110m dataset seems ideal for use in a country selector widget in kdelibs. The 1:50m dataset is less detailed than the current MWDBII so may be less useful.

Using the data in the default shapefile format is not considered desirable however:
* No shapefile format support in Marble (yet), would have to rely on an external library or write our own
* Space inefficient (14Mb vs 2.6Mb for MWDBII)
* No zoom level attribute or any node level attributes which would slow drawing
* Vector level attributes are stored in .dbf format which adds complexity to implementing shapefile support

The ideal solution would seem be to convert the Natural Earth data into a more efficient file format and either calculate and store the zoom level attribute in the file or calculate it on file load. The full Natural Earth dataset would be converted, but would only ship the minimal dataset required with Marble (approx 4-5Mb?) with the remainder of the data later being downloaded via GHNS or as a separate package.

=== Vector Layer Improvements ===

The main changes required to Marble will be in the vector layer itself, removing the old PNT file vector drawing code and implementing the new dataset using the new GeoData library vector support.

Two main issues will need to be solved here
* if a new file format is needed for efficient storage
* if a zoom level attribute is needed for fast drawing, and if so where and how to implement the attribute

Some possibilities for the file format are:
* Adapt the existing PNT format used for MWDBII to have a higher degree of accuracy and add an attributes table
* Use the existing Marble serial/cache format which will be faster but the size efficiency may not be sufficient
* Use shapefile by implementing a lightweight parser without dbf support but our own simple attribute table.
* Implement full shapefile support including dbf (possibly using libshape)

The zoom level problem can be solved by either:
* Calculate a zoom level for each point during the file conversion and save it in the new file format, but this will require more storage space.
* Improve the vector drawing layer to calculate the zoom level on the fly, which would benefit all vector drawing but may be too slow.

The Douglas-Peucker algorithm may be able to be used here.

Some pros/cons to consider:

* The 1:10m country file is 6.55MB and contains 533,202 points = 12.28
bytes/point compared to the PNT which is 745KB and contains 127,246 points =
5.85 bytes/point, which would suggest the NE data in PNT format would be half
the size, so 6 MB in total. This could probably be further reduced by a light
application of Douglas-Peucker.

* The NE shapefiles have been carefully processed so shared borders and
overlapping features like rivers match exactly and other such niceties,
applying the Douglas-Peucker algorithm might affect that.

* A shapefile parser would allow users/apps to load other shapefiles.

* We would have to reconvert and check the data every time there's a new NE
release which could be a lot of effort, but an automated shp2pnt script could
prove useful to allow apps/users to display their own shapefiles in a simple
way.

* It is unknown if the D-H algorithm can be deployed in a way to mark each point with a detail level rather than just throwing the points away.

==== Calculating Zoom Level on the fly ====
Using GeoPainter and GeoDataLineString ("libgeodata"):
* Apply Douglas-Peuker dynamically in GeoDataLineString class to set Detail Level
* When GeoDataLineString modified (add/del point) set dirty flag
* When node accessed for drawing, Dirty flag would trigger D-P to calculate detail level and unset dirty flag
* Would benefit all vector formats, e.g. kml, ppx, shp

==== Possible new file format ====
Potential new Marble file format based on PNT:
* 1st integer (32 bit): Latitude in arcseconds highest bit indicates new polygon starts: header information has to be read from 3rd integer
* 2nd integer (32 bit): Longitude in arcseconds
* Optional 3rd integer: feature key highest bit feature geometry (line or ring).

Applying this to the 1:10m dataset:
* Each point takes 64 bits/8 bytes
* The start of each polygon takes 96 bits
* Roughly 533,202 x 8 bytes = 4 Mb for the country borders alone, not including internal border and coastline files
* If that's too much to ship, then ship the 1:50m dataset as the default and download the 1:10m dataset once online

==== Attribute Database ====

Metadata file:
* convert / filter dbf into our own format
* could just be csv or xml? or sqlite?

Rather than the Geonames ID, we could just use the Natural Earth object ID,
then a look-up file/table that matches the NE ID to the ISO / FIPS / whatever
code (NE provides this in the metadata) and Geonames ID (which we would have
to provide). This would allow look-ups via whatever code or ID is available,
and we wouldn't be reliant on Geonames IDs staying constant or being online.

==== Spatialite ====

One option would be to integrate Spatialite and use this as both the data storage for the vectors and as the attribute database. Spatialite is an extension to SQLite implementing a Spatial SQL database. Among the feature this provides is a compact data storage format and the ability to import Shapefiles and CSV files, as well as access all the standard GEOS tools if installed.

There is a 20Mb zip file available for Natural Earth in Spatialite format, it is unclear how much of Natural Earth is contained in this. A minimal dataset could be shipped by default with the full dataset downloaded later.

Spatial SQL queries could return just those vectors currently in the viewport, but repeated reloading and redrawing could be inefficent. However this may also solve the Level-of-Detail problem.

More research is required here. It may not be a suitable option for the default Atlas view, but would be a very powerful extension for Marble to provide lightweight GIS-like functionality.

=== Action Plan ===

A possible action plan is
# Fix GeoPainter LinearRings which contain a pole not rendered correctly
# Implement Douglas-Peucker reduction in GeoDataLineString
# New PNT file format definition (with a different name, MBL?)
# Metadata file format definition
# New GeoData PNT2 file loading code (convert old data).
# shp2pnt2 script to convert shp to new formats (using Perl::shp? there's shp2xxx scripts out there we could copy?), including matching to Geonames ID
# split files into 'ship with', 'download asap', 'ghns'

Later add simple shapefile loading to GeoData, maybe with attibute layer?

== Natural Earth Datasets ==

=== Dataset Sizes ===

Key Natural Earth data files from v1.2, recent updates to 1.3 not included.
<pre>
1:110m 1:50m 1:10m
------ ------- -------
Admin level 0 countries 172 KB 1.36 MB 6.55 MB
Admin level 0 land borders 39 KB 301 KB 896 KB
Admin level 0 sea borders 12 KB 40 KB 79 KB
Admin level 0 disputed 40 KB 157 KB
Admin level 1 regions 39 KB 339 MB 13.9 MB *
Admin level 1 land borders 16 KB 60 KB 4.82 MB
Coastlines 79 KB 883 KB 2.15 MB
Rivers 19 KB 420 KB 3.29 MB
Lakes 10 KB 286 KB 786 MB
Glaciers 13 KB 208 KB 1.23 MB
Dateline 18 KB 18 KB 18 KB
Playas 18 KB 106 KB
Ice Shelves 105 KB 211 KB
Minor Islands 449 KB
Reefs 171 KB
------- ------- ---------
417 KB 4.08 MB 34.03 MB

* level 1 regions are USA/Canada only at 110m and 50m, but whole world at 10m,
perfect for KGeography use :-)

Other useful files:
Physical Features Land 146 KB 1.50 MB 692 KB
Physical Features Sea 348 KB 836 KB 836 MB
Populated Places 347 KB 1.48 MB
Urban Areas 439 KB 3.48 MB
Bathmetry 11.64 MB

</pre>

=== Dataset Details ===

* Countries
** matched boundary lines and polygons with names attributes for countries and
sovereign states. Includes dependencies (French Polynesia),
map units (U.S. Pacific Island Territories) and
sub-national map subunits (Corsica versus mainland Metropolitan France).
** Core data

* Disputed areas and breakaway regions
** From Kashmir to the Elemi Triangle, Northern Cyprus to Western Sahara.
** Core data

* Internal boundaries
** Core data??

* Coastline
** ocean coastline, including major islands. Coastline is matched to land and water polygons.
** Core data?

* First order admin (provinces, departments, states, etc.)
** internal boundaries and polygons for all but a few tiny island nations. Includes names attributes and some statistical groupings of the same for smaller countries.
** Optional download

* Populated places
** point symbols with name attributes. Includes capitals, major cities and towns, plus significant smaller towns in sparsely inhabited regions. We favor regional significance over population census in determining rankings.
** Optional download, or use to replace current places file?

* Urban polygons
** derived from 2002-2003 MODIS satellite data.
** Optional download

* Pacific nation groupings
** boxes for keeping these far-flung islands tidy.
** Optional download

* Water boundary indicators
** partial selection of key 200-mile nautical limits, plus some disputed, treaty, and median lines.
** Optional download

* Land
** Land polygons including major islands
** Optional download

* Ocean
** Ocean polygon split into contiguous pieces.
** Optional download

* Minor Islands
** additional small ocean islands ranked to two levels of relative importance.
** Optional download

* Reefs
** major coral reefs from WDB2.
** Optional download

* Physical region features
** polygon and point labels of major physical features.
** Optional download

* Rivers and Lake Centerlines
** ranked by relative importance. Includes name and line width attributes. Don’t want minor lakes? Turn on their centerlines to avoid unseemly data gaps.
** Optional download

* Lakes
** Ranked by relative importance, coordinating with river ranking. Includes name attributes.
** Optional download

*Glaciated areas
** polygons derived from DCW, except for Antarctica derived from MOA. Includes name attributes for major polar glaciers.
** Optional download

*Antarctic ice shelves
** Derived from 2003-2004 MOA. Reflects recent ice shelf collapses.
** Optional download

*Bathymetry
** nested polygons at 0, -200, -1,000, -2,000, -3,000, -4,000, -5,000, -6,000, -7,000, -8,000, -9,000,and -10,000 meters. Created from SRTM Plus.
** Optional download

* Parks and protected areas
** US Only
** Don't use, maybe user download layer

* Geographic lines
** Polar circles, tropical circles, equator, and International Date Line.
** Probably not useful to Marble as we have a plugin for most of these.
** International Date Line could be extracted

*Graticules
** 1-, 5-, 10-, 15-, 20-, and 30-degree increments. Includes WGS84 bounding box.
** Probably not useful to Marble as we have a Graticle plugin.

Projects/Marble/NaturalEarth

2012-05-01T11:23:04Z

Odysseus: /* Attribute Database */

= Natural Earth =

== Introduction ==

Marble currently uses the very old and outdated MWDBII dataset for its vector base map such as national borders and coastlines and we really need to replace it with more up-to-date data. However, MWDBII has two key advantages, it is very compact in size enabling Marble to ship it by default, and the individual nodes have a zoom level value which speeds up drawing.

The current vector layer also has the disadvantage of not being able to be manipulated either programtiacally or by the user. This prevents it from being used for such things as KGeography or other educational uses where you would want to select and manipulate a geographic entity.

Improving the vector base maps would thus consist of two closely related parts:
* Improving the vector drawing code to allow interaction with the vectors, and improved performance to allow more detailed vectors to be drawn.
* Importing a new base layer dataset.

== Using NaturalEarth ==

The [http://www.naturalearthdata.com/ Natural Earth data set] is a "public domain map dataset available at 1:10m, 1:50m, and 1:110 million scales. Featuring tightly integrated vector and raster data, with Natural Earth you can make a variety of visually pleasing, well-crafted maps with cartography or GIS software." This data set seems ideal as a replacement for the MWDBII.

Advantages:
* Free / Public Domain data
* Regularly updated
* Wide variety of political and geographic features
* Available at 3 different scales: 1:10m 1:50m and 1:110m
* All feature nodes at same scale are matched
* Data attributes such as country code, population, relative magnitude, etc

Disadvantages:
* Is in Shapefile format which is space inefficient
* No per node zoom level attribute
* Different scale datasets do not match so cannot efficiently be used together for zooming

The 1:10m dataset seems ideal as the base map in Marble as it provides a higher level of detail than the current MWDBII. The 1:110m dataset seems ideal for use in a country selector widget in kdelibs. The 1:50m dataset is less detailed than the current MWDBII so may be less useful.

Using the data in the default shapefile format is not considered desirable however:
* No shapefile format support in Marble (yet), would have to rely on an external library or write our own
* Space inefficient (14Mb vs 2.6Mb for MWDBII)
* No zoom level attribute or any node level attributes which would slow drawing
* Vector level attributes are stored in .dbf format which adds complexity to implementing shapefile support

The ideal solution would seem be to convert the Natural Earth data into a more efficient file format and either calculate and store the zoom level attribute in the file or calculate it on file load. The full Natural Earth dataset would be converted, but would only ship the minimal dataset required with Marble (approx 4-5Mb?) with the remainder of the data later being downloaded via GHNS or as a separate package.

=== Vector Layer Improvements ===

The main changes required to Marble will be in the vector layer itself, removing the old PNT file vector drawing code and implementing the new dataset using the new GeoData library vector support.

Two main issues will need to be solved here
* if a new file format is needed for efficient storage
* if a zoom level attribute is needed for fast drawing, and if so where and how to implement the attribute

Some possibilities for the file format are:
* Adapt the existing PNT format used for MWDBII to have a higher degree of accuracy and add an attributes table
* Use the existing Marble serial/cache format which will be faster but the size efficiency may not be sufficient
* Use shapefile by implementing a lightweight parser without dbf support but our own simple attribute table.
* Implement full shapefile support including dbf (possibly using libshape)

The zoom level problem can be solved by either:
* Calculate a zoom level for each point during the file conversion and save it in the new file format, but this will require more storage space.
* Improve the vector drawing layer to calculate the zoom level on the fly, which would benefit all vector drawing but may be too slow.

The Douglas-Peucker algorithm may be able to be used here.

Some pros/cons to consider:

* The 1:10m country file is 6.55MB and contains 533,202 points = 12.28
bytes/point compared to the PNT which is 745KB and contains 127,246 points =
5.85 bytes/point, which would suggest the NE data in PNT format would be half
the size, so 6 MB in total. This could probably be further reduced by a light
application of Douglas-Peucker.

* The NE shapefiles have been carefully processed so shared borders and
overlapping features like rivers match exactly and other such niceties,
applying the Douglas-Peucker algorithm might affect that.

* A shapefile parser would allow users/apps to load other shapefiles.

* We would have to reconvert and check the data every time there's a new NE
release which could be a lot of effort, but an automated shp2pnt script could
prove useful to allow apps/users to display their own shapefiles in a simple
way.

* It is unknown if the D-H algorithm can be deployed in a way to mark each point with a detail level rather than just throwing the points away.

==== Calculating Zoom Level on the fly ====
Using GeoPainter and GeoDataLineString ("libgeodata"):
* Apply Douglas-Peuker dynamically in GeoDataLineString class to set Detail Level
* When GeoDataLineString modified (add/del point) set dirty flag
* When node accessed for drawing, Dirty flag would trigger D-P to calculate detail level and unset dirty flag
* Would benefit all vector formats, e.g. kml, ppx, shp

==== Possible new file format ====
Potential new Marble file format based on PNT:
* 1st integer (32 bit): Latitude in arcseconds highest bit indicates new polygon starts: header information has to be read from 3rd integer
* 2nd integer (32 bit): Longitude in arcseconds
* Optional 3rd integer: feature key highest bit feature geometry (line or ring).

Applying this to the 1:10m dataset:
* Each point takes 64 bits/8 bytes
* The start of each polygon takes 96 bits
* Roughly 533,202 x 8 bytes = 4 Mb for the country borders alone, not including internal border and coastline files
* If that's too much to ship, then ship the 1:50m dataset as the default and download the 1:10m dataset once online

==== Attribute Database ====

Metadata file:
* convert / filter dbf into our own format
* could just be csv or xml? or sqlite?

Rather than the Geonames ID, we could just use the Natural Earth object ID,
then a look-up file/table that matches the NE ID to the ISO / FIPS / whatever
code (NE provides this in the metadata) and Geonames ID (which we would have
to provide). This would allow look-ups via whatever code or ID is available,
and we wouldn't be reliant on Geonames IDs staying constant or being online.

=== Spatialite ===

One option would be to integrate Spatialite and use this as both the data storage for the vectors and as the attribute database. Spatialite is an extension to SQLite implementing a Spatial SQL database. Among the feature this provides is a compact data storage format and the ability to import Shapefiles and CSV files, as well as access all the standard GEOS tools if installed.

There is a 20Mb zip file available for Natural Earth in Spatialite format, it is unclear how much of Natural Earth is contained in this. A minimal dataset could be shipped by default with the full dataset downloaded later.

Spatial SQL queries could return just those vectors currently in the viewport, but repeated reloading and redrawing could be inefficent. However this may also solve the Level-of-Detail problem.

More research is required here. It may not be a suitable option for the default Atlas view, but would be a very powerful extension for Marble to provide lightweight GIS-like functionality.

=== Action Plan ===

A possible action plan is
# Fix GeoPainter LinearRings which contain a pole not rendered correctly
# Implement Douglas-Peucker reduction in GeoDataLineString
# New PNT file format definition (with a different name, MBL?)
# Metadata file format definition
# New GeoData PNT2 file loading code (convert old data).
# shp2pnt2 script to convert shp to new formats (using Perl::shp? there's shp2xxx scripts out there we could copy?), including matching to Geonames ID
# split files into 'ship with', 'download asap', 'ghns'

Later add simple shapefile loading to GeoData, maybe with attibute layer?

== Natural Earth Datasets ==

=== Dataset Sizes ===

Key Natural Earth data files from v1.2, recent updates to 1.3 not included.
<pre>
1:110m 1:50m 1:10m
------ ------- -------
Admin level 0 countries 172 KB 1.36 MB 6.55 MB
Admin level 0 land borders 39 KB 301 KB 896 KB
Admin level 0 sea borders 12 KB 40 KB 79 KB
Admin level 0 disputed 40 KB 157 KB
Admin level 1 regions 39 KB 339 MB 13.9 MB *
Admin level 1 land borders 16 KB 60 KB 4.82 MB
Coastlines 79 KB 883 KB 2.15 MB
Rivers 19 KB 420 KB 3.29 MB
Lakes 10 KB 286 KB 786 MB
Glaciers 13 KB 208 KB 1.23 MB
Dateline 18 KB 18 KB 18 KB
Playas 18 KB 106 KB
Ice Shelves 105 KB 211 KB
Minor Islands 449 KB
Reefs 171 KB
------- ------- ---------
417 KB 4.08 MB 34.03 MB

* level 1 regions are USA/Canada only at 110m and 50m, but whole world at 10m,
perfect for KGeography use :-)

Other useful files:
Physical Features Land 146 KB 1.50 MB 692 KB
Physical Features Sea 348 KB 836 KB 836 MB
Populated Places 347 KB 1.48 MB
Urban Areas 439 KB 3.48 MB
Bathmetry 11.64 MB

</pre>

=== Dataset Details ===

* Countries
** matched boundary lines and polygons with names attributes for countries and
sovereign states. Includes dependencies (French Polynesia),
map units (U.S. Pacific Island Territories) and
sub-national map subunits (Corsica versus mainland Metropolitan France).
** Core data

* Disputed areas and breakaway regions
** From Kashmir to the Elemi Triangle, Northern Cyprus to Western Sahara.
** Core data

* Internal boundaries
** Core data??

* Coastline
** ocean coastline, including major islands. Coastline is matched to land and water polygons.
** Core data?

* First order admin (provinces, departments, states, etc.)
** internal boundaries and polygons for all but a few tiny island nations. Includes names attributes and some statistical groupings of the same for smaller countries.
** Optional download

* Populated places
** point symbols with name attributes. Includes capitals, major cities and towns, plus significant smaller towns in sparsely inhabited regions. We favor regional significance over population census in determining rankings.
** Optional download, or use to replace current places file?

* Urban polygons
** derived from 2002-2003 MODIS satellite data.
** Optional download

* Pacific nation groupings
** boxes for keeping these far-flung islands tidy.
** Optional download

* Water boundary indicators
** partial selection of key 200-mile nautical limits, plus some disputed, treaty, and median lines.
** Optional download

* Land
** Land polygons including major islands
** Optional download

* Ocean
** Ocean polygon split into contiguous pieces.
** Optional download

* Minor Islands
** additional small ocean islands ranked to two levels of relative importance.
** Optional download

* Reefs
** major coral reefs from WDB2.
** Optional download

* Physical region features
** polygon and point labels of major physical features.
** Optional download

* Rivers and Lake Centerlines
** ranked by relative importance. Includes name and line width attributes. Don’t want minor lakes? Turn on their centerlines to avoid unseemly data gaps.
** Optional download

* Lakes
** Ranked by relative importance, coordinating with river ranking. Includes name attributes.
** Optional download

*Glaciated areas
** polygons derived from DCW, except for Antarctica derived from MOA. Includes name attributes for major polar glaciers.
** Optional download

*Antarctic ice shelves
** Derived from 2003-2004 MOA. Reflects recent ice shelf collapses.
** Optional download

*Bathymetry
** nested polygons at 0, -200, -1,000, -2,000, -3,000, -4,000, -5,000, -6,000, -7,000, -8,000, -9,000,and -10,000 meters. Created from SRTM Plus.
** Optional download

* Parks and protected areas
** US Only
** Don't use, maybe user download layer

* Geographic lines
** Polar circles, tropical circles, equator, and International Date Line.
** Probably not useful to Marble as we have a plugin for most of these.
** International Date Line could be extracted

*Graticules
** 1-, 5-, 10-, 15-, 20-, and 30-degree increments. Includes WGS84 bounding box.
** Probably not useful to Marble as we have a Graticle plugin.

Development/Git

2012-04-29T17:18:40Z

Odysseus:

<languages />
<translate>

This is the hub page for all information about the use of Git by KDE.

== KDE and Git == 


This section provides details on using the KDE Git infrastructure. This is intended for use by KDE developers to find out how KDE uses Git and how to set up Git for use with KDE.


The [http://community.kde.org/Sysadmin/GitKdeOrgManual KDE Git System Administrators Manual] is a useful resource for more details on the technical implementation of the KDE Git infrastructure.

For more information on how the KDE Git Repositories are organized, please see the [[Getting_Started/Sources|Sources]] page or the [https://projects.kde.org/projects KDE Git Projects] page.

Please note that some KDE modules are still using SVN, for more details read the [[Getting_Started/Sources/Using_Subversion_with_KDE|Using Subversion with KDE]] page.

=== KDE Git Configuration === 


How to configure Git for use with the KDE infrastructure.


Please see the [[Special:myLanguage/Development/Git/Configuration|Git Configuration page]].

=== KDE Git Policies === 


KDE policies on Git. More generic development policies go elsewhere.

=== KDE Git Recipes === 


Short recipes for using Git with the KDE infrastructure.


Please see the [[Special:myLanguage/Development/Git/Recipes|Git Recipes page]].

=== KDE Git Tutorials === 


More in-depth instructions in using Git.


* [[Special:myLanguage/Development/Tutorials/Git/GitQuickStart|A quick step-by-step guide for getting started]]


* [[Special:myLanguage/Development/Tutorials/Git/Create a patch|Creating a patch]]


Please help filling this section by
* checking the links at the bottom of the page and see which still have valid content
* write tutorials yourself

== External Git Resources == 


Links to useful external sites about Git

=== Official Documentation === 


* [http://git-scm.com/documentation Links to git official documentation]

=== Git for SVN Users === 


* [http://git-scm.com/course/svn.html The git-svn Crash Course]

=== Git books === 


* [http://progit.org/book/ Pro Git] - An easy to understand book on git (CC licensed).


* [http://book.git-scm.com/ The git community book], also as a [http://book.git-scm.com/book.pdf pdf]

=== Tutorials === 


* [http://www-cs-students.stanford.edu/~blynn/gitmagic/ Git Magic] - A good intro to git (in several languages!)


*[http://tom.preston-werner.com/2009/05/19/the-git-parable.html The Git Parable]
- Essential reading if you want to truly understand git.


* [http://www.gitcasts.com/ Git Screencasts]

=== Cheat Sheets === 


* [http://cheat.errtheblog.com/s/git Quick reference]


* [http://zrusin.blogspot.com/2007/09/git-cheat-sheet.html Illustrated git cheat sheet]
(broken image, get it from [[Media:Zrusin-git-cheat-sheet-medium.png]])

= Documentation Changes = 

== KDE Documentation Review == 

=== Existing Pages For Review === 


Existing KDE pages about Git, SVN, and/or buildinga KDE that need to be revised. When revising pages try to split the generic development and revision control policies separate from Git specific stuff. Do not refer to "the KDE Git Repository" but instead the "KDE Code Repository". Lots of small simple pages that are less daunting to newbies and can be linked to from multiple locations are preferred to massive walls of text.


Keep:


* [[Special:myLanguage/Development/Tutorials/Git/Basics|Basics]]


* [[Special:myLanguage/Development/Tutorials/Git/git-svn|Git-svn]]


* [[Special:myLanguage/Development/Tutorials/Git/kde-qt| Kde-qt]]


* [[Special:myLanguage/Getting Started/Sources/Amarok Git Tutorial| The Amarok Git Tutorial]]


On community.kde.org:


* [http://community.kde.org/Sysadmin/GitKdeOrgManual Git-KDE Manual]


* [http://community.kde.org/20110213_GitWorkflowAgenda Git Workflow Agenda]


* [http://community.kde.org/20110213_GitWorkflowAgenda/StevesIdea Git Workflow Agenda, Steve's Idea]


On techbase.kde.org:


* [[Special:myLanguage/Getting Started|Getting Started]]


* [[Special:myLanguage/Getting Started/Build/KDE4| Build KDE 4]]


* [[Special:myLanguage/Getting Started/Build/KDE4.x|Build KDE 4.x]]


* [[Special:myLanguage/Getting Started/Build/KDE4/Prerequisites|Prerequisites]]


* [[Special:myLanguage/Getting Started/Build/KDE4/Windows/subversion|Subversion on Windows]]


* [[Special:myLanguage/Getting_Started/Increased_Productivity_in_KDE4_with_Scripts|Increase Productivity with Scripts]]


* [[Special:myLanguage/Getting_Started/Build/kdesrc-build|Kdesrc-build]]


* [[Special:myLanguage/Getting Started/Sources/Anonymous SVN|Anonymous SVN]]


* [[Special:myLanguage/Getting_Started/Sources/Using_Subversion_with_KDE|Subversion with KDE]]


* [[Special:myLanguage/Getting_Started/Using_an_IDE_with_KDE4|Using an IDE with KDE 4]]


* [[Special:myLanguage/Policies/SVN_Commit_Policy|SVN Commit Policy]]


* [[Special:myLanguage/Policies/SVN_Guidelines|SVN Guidelines]]


* [[Special:myLanguage/Development/Tools|Development Tools]]


* [[Special:myLanguage/Development/Tutorials/Git/Recipes|Git Recipes]]


* [[Special:myLanguage/Development/Tutorials/Git/decoding-git|Decoding Git]]


* [[Special:myLanguage/Projects/rekonq/Git_with_rekonq_HowTo|Git with Rekonq How-to]]


* [[Special:myLanguage/Projects/Related/Subversion|Subversion]]


* [[Special:myLanguage/Projects/MovetoGit|Move to Git]]


* [[Special:myLanguage/Projects/MoveToGit/StepsToMove|Steps to Move]]


* [[Special:myLanguage/Contribute/Get a SVN Account|Get a SVN Account]]


* [[Special:myLanguage/Contribute/First Steps with your KDE SVN Account|First Steps with your KDE SVN Account]]


There are also numerous other pages referring to "the KDE SVN/subversion repositories" which should be replaced with the generic "KDE code repositories".


There are also numerous translated pages which will need to be updated once the original pages are completed.

=== New Page Structure === 


* [[Special:myLanguage/Getting_Started|Getting Started]]


* [[Special:myLanguage/Getting_Started/Build|Getting_Started/Build]]


* [[Special:myLanguage/Getting_Started/Build/Environment|Getting_Started/Build/Environment]]


* [[Special:myLanguage/Getting_Started/Build/Requirements|Getting_Started/Build/Requirements]]


* [[Special:myLanguage/Getting_Started/Build/Qt|Getting_Started/Build/Q]]


* [[Special:myLanguage/Getting_Started/Build/KdeSupport|Getting_Started/Build/KdeSupport]]


* [[Special:myLanguage/Getting_Started/Build/Windows|Getting_Started/Build/Windows]]


* [[Special:myLanguage/Getting_Started/Build/Mac_OS_X|Getting_Started/Build/Mac_OS_X]]


* [[Special:myLanguage/Getting_Started/Run/Shell|Getting_Started/Run/Shell]]


* [[Special:myLanguage/Getting_Started/Run/Nested_Session|Getting_Started/Run/Nested_Session]]


* [[Special:myLanguage/Getting_Started/Run/Full_Session|Getting_Started/Run/Full_Session>]]
</translate>

Development/Git

2012-04-29T17:18:16Z

Odysseus: /* KDE and Git */

<languages />
<translate>

This is the hub page for all information about the use of Git by KDE.


This page is a work in progress where all new Git material is being organised. Most of these sections will eventually be moved to their own pages. Feel free to add stuff.

== KDE and Git == 


This section provides details on using the KDE Git infrastructure. This is intended for use by KDE developers to find out how KDE uses Git and how to set up Git for use with KDE.


The [http://community.kde.org/Sysadmin/GitKdeOrgManual KDE Git System Administrators Manual] is a useful resource for more details on the technical implementation of the KDE Git infrastructure.

For more information on how the KDE Git Repositories are organized, please see the [[Getting_Started/Sources|Sources]] page or the [https://projects.kde.org/projects KDE Git Projects] page.

Please note that some KDE modules are still using SVN, for more details read the [[Getting_Started/Sources/Using_Subversion_with_KDE|Using Subversion with KDE]] page.

=== KDE Git Configuration === 


How to configure Git for use with the KDE infrastructure.


Please see the [[Special:myLanguage/Development/Git/Configuration|Git Configuration page]].

=== KDE Git Policies === 


KDE policies on Git. More generic development policies go elsewhere.

=== KDE Git Recipes === 


Short recipes for using Git with the KDE infrastructure.


Please see the [[Special:myLanguage/Development/Git/Recipes|Git Recipes page]].

=== KDE Git Tutorials === 


More in-depth instructions in using Git.


* [[Special:myLanguage/Development/Tutorials/Git/GitQuickStart|A quick step-by-step guide for getting started]]


* [[Special:myLanguage/Development/Tutorials/Git/Create a patch|Creating a patch]]


Please help filling this section by
* checking the links at the bottom of the page and see which still have valid content
* write tutorials yourself

== External Git Resources == 


Links to useful external sites about Git

=== Official Documentation === 


* [http://git-scm.com/documentation Links to git official documentation]

=== Git for SVN Users === 


* [http://git-scm.com/course/svn.html The git-svn Crash Course]

=== Git books === 


* [http://progit.org/book/ Pro Git] - An easy to understand book on git (CC licensed).


* [http://book.git-scm.com/ The git community book], also as a [http://book.git-scm.com/book.pdf pdf]

=== Tutorials === 


* [http://www-cs-students.stanford.edu/~blynn/gitmagic/ Git Magic] - A good intro to git (in several languages!)


*[http://tom.preston-werner.com/2009/05/19/the-git-parable.html The Git Parable]
- Essential reading if you want to truly understand git.


* [http://www.gitcasts.com/ Git Screencasts]

=== Cheat Sheets === 


* [http://cheat.errtheblog.com/s/git Quick reference]


* [http://zrusin.blogspot.com/2007/09/git-cheat-sheet.html Illustrated git cheat sheet]
(broken image, get it from [[Media:Zrusin-git-cheat-sheet-medium.png]])

= Documentation Changes = 

== KDE Documentation Review == 

=== Existing Pages For Review === 


Existing KDE pages about Git, SVN, and/or buildinga KDE that need to be revised. When revising pages try to split the generic development and revision control policies separate from Git specific stuff. Do not refer to "the KDE Git Repository" but instead the "KDE Code Repository". Lots of small simple pages that are less daunting to newbies and can be linked to from multiple locations are preferred to massive walls of text.


Keep:


* [[Special:myLanguage/Development/Tutorials/Git/Basics|Basics]]


* [[Special:myLanguage/Development/Tutorials/Git/git-svn|Git-svn]]


* [[Special:myLanguage/Development/Tutorials/Git/kde-qt| Kde-qt]]


* [[Special:myLanguage/Getting Started/Sources/Amarok Git Tutorial| The Amarok Git Tutorial]]


On community.kde.org:


* [http://community.kde.org/Sysadmin/GitKdeOrgManual Git-KDE Manual]


* [http://community.kde.org/20110213_GitWorkflowAgenda Git Workflow Agenda]


* [http://community.kde.org/20110213_GitWorkflowAgenda/StevesIdea Git Workflow Agenda, Steve's Idea]


On techbase.kde.org:


* [[Special:myLanguage/Getting Started|Getting Started]]


* [[Special:myLanguage/Getting Started/Build/KDE4| Build KDE 4]]


* [[Special:myLanguage/Getting Started/Build/KDE4.x|Build KDE 4.x]]


* [[Special:myLanguage/Getting Started/Build/KDE4/Prerequisites|Prerequisites]]


* [[Special:myLanguage/Getting Started/Build/KDE4/Windows/subversion|Subversion on Windows]]


* [[Special:myLanguage/Getting_Started/Increased_Productivity_in_KDE4_with_Scripts|Increase Productivity with Scripts]]


* [[Special:myLanguage/Getting_Started/Build/kdesrc-build|Kdesrc-build]]


* [[Special:myLanguage/Getting Started/Sources/Anonymous SVN|Anonymous SVN]]


* [[Special:myLanguage/Getting_Started/Sources/Using_Subversion_with_KDE|Subversion with KDE]]


* [[Special:myLanguage/Getting_Started/Using_an_IDE_with_KDE4|Using an IDE with KDE 4]]


* [[Special:myLanguage/Policies/SVN_Commit_Policy|SVN Commit Policy]]


* [[Special:myLanguage/Policies/SVN_Guidelines|SVN Guidelines]]


* [[Special:myLanguage/Development/Tools|Development Tools]]


* [[Special:myLanguage/Development/Tutorials/Git/Recipes|Git Recipes]]


* [[Special:myLanguage/Development/Tutorials/Git/decoding-git|Decoding Git]]


* [[Special:myLanguage/Projects/rekonq/Git_with_rekonq_HowTo|Git with Rekonq How-to]]


* [[Special:myLanguage/Projects/Related/Subversion|Subversion]]


* [[Special:myLanguage/Projects/MovetoGit|Move to Git]]


* [[Special:myLanguage/Projects/MoveToGit/StepsToMove|Steps to Move]]


* [[Special:myLanguage/Contribute/Get a SVN Account|Get a SVN Account]]


* [[Special:myLanguage/Contribute/First Steps with your KDE SVN Account|First Steps with your KDE SVN Account]]


There are also numerous other pages referring to "the KDE SVN/subversion repositories" which should be replaced with the generic "KDE code repositories".


There are also numerous translated pages which will need to be updated once the original pages are completed.

=== New Page Structure === 


* [[Special:myLanguage/Getting_Started|Getting Started]]


* [[Special:myLanguage/Getting_Started/Build|Getting_Started/Build]]


* [[Special:myLanguage/Getting_Started/Build/Environment|Getting_Started/Build/Environment]]


* [[Special:myLanguage/Getting_Started/Build/Requirements|Getting_Started/Build/Requirements]]


* [[Special:myLanguage/Getting_Started/Build/Qt|Getting_Started/Build/Q]]


* [[Special:myLanguage/Getting_Started/Build/KdeSupport|Getting_Started/Build/KdeSupport]]


* [[Special:myLanguage/Getting_Started/Build/Windows|Getting_Started/Build/Windows]]


* [[Special:myLanguage/Getting_Started/Build/Mac_OS_X|Getting_Started/Build/Mac_OS_X]]


* [[Special:myLanguage/Getting_Started/Run/Shell|Getting_Started/Run/Shell]]


* [[Special:myLanguage/Getting_Started/Run/Nested_Session|Getting_Started/Run/Nested_Session]]


* [[Special:myLanguage/Getting_Started/Run/Full_Session|Getting_Started/Run/Full_Session>]]
</translate>

Getting Started/Build/KDE Development Platform

2012-03-18T18:54:15Z

Odysseus: /* KDE Runtime */

{{Template:I18n/Language Navigation Bar|Getting_Started/Build/KDE_Development_Platform}}

{{TutorialBrowser|
series=Getting Started|
name=Building KDE4 From Source/KDE Development Platform|
pre=[[../KDE_Support|KDE Support]]|
next=[[../KDE_Workspace|KDE Workspace]]|
|
}}

== Introduction ==

The KDE Development Platform contains a number of KDE modules that form the foundation for all KDE Software.

If you are only interested in developing a KDE Application and not the KDE Development Platform itself then your distribution packages may be sufficient for these requirements, but Unstable development may require the latest Unstable versions to be built from source.

=== Required Steps ===

You need to have completed the following steps:
* Set up your [[../Environment|Build Environment]]
* Selected your [[../Recipes|Build Recipes]]
* Installed the [[../Requirements|System Requirements]]
* Installed or Built [[../Qt|Qt and related requirements]]
* Installed or Built [[../KDE_Support|KDE Support]]
* Understand the [[../Requirements#Definitions|Requirements Table format]]

== KDE Libraries ==

KDE Libraries (kdelibs) is the core library of the KDE Development Platform.

{| border="1" cellpadding="5" cellspacing="0"
|-
| width="25%" style="background-color:#EFEFEF;" | '''Project Page'''
| width="75%" | [https://projects.kde.org/projects/kde/kdelibs https://projects.kde.org/projects/kde/kdelibs]
|-
| style="background-color:#EFEFEF;" | '''Easy Repository'''
| git clone kde:kdelibs.git
|-
| style="background-color:#EFEFEF;" | '''Full Repository'''
| git clone git://anongit.kde.org/kdelibs.git
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''KDE Libraries Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http://oscaf.sourceforge.net Shared desktop ontologies]
| style="background-color:#FFFFFF" | ??
| style="background-color:#FFFF66" | >= 0.6.50
| ??
| Support for the Nepomuk semantic desktop system.<br />This is needed if you intend to install ''kdepimlibs''
|-
| [http://www.grantlee.org Grantlee]
| style="background-color:#FFFFFF" | ??
| style="background-color:#66FF66" | >= 0.1.0
| ??
| Grantlee is used for generating compilable code by the ModelEventLogger.<br />Without Grantlee, the logger will do nothing.
|-
| [http://aspell.net Aspell]
| style="background-color:#FFFFFF" |
| style="background-color:#66FF66" |
| ??
| Spell checking support via Aspell.
|-
| [http://ivrix.org.il/projects/spell-checker/ HSpell]
| style="background-color:#FFFFFF" |
| style="background-color:#66FF66" |
| ??
| Spell checking support for Hebrew.
|}

== KDE PIM Libraries ==

KDE PIM Libraries (kdepimlibs) is the PIM library of the KDE Development Platform.

{| border="1" cellpadding="5" cellspacing="0"
|-
| width="25%" style="background-color:#EFEFEF;" | '''Project Page'''
| width="75%" | [https://projects.kde.org/projects/kde/kdepimlibs https://projects.kde.org/projects/kde/kdepimlibs]
|-
| style="background-color:#EFEFEF;" | '''Easy Repository'''
| git clone kde:kdepimlibs.git
|-
| style="background-color:#EFEFEF;" | '''Full Repository'''
| git clone git://anongit.kde.org/kdepimlibs.git
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''KDE PIM Libraries Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http:// Project]
| style="background-color:#FF6666" |
| style="background-color:#FF6666" |
| Yes
| A library for
|}

=== Troubleshooting ===

If cmake tells you that it can not find ''Nepomuk'', it may be that you are missing some of the nepomuk dependencies of kdelibs.

The solution is to rebuild kdelibs with the missing dependencies.

== KDE Runtime ==

KDE Runtime (kde-runtime) is the runtime component of the KDE Development Platform.

{| border="1" cellpadding="5" cellspacing="0"
|-
| width="25%" style="background-color:#EFEFEF;" | '''Project Page'''
| width="75%" | [https://projects.kde.org/projects/kde/kde-runtime/ https://projects.kde.org/projects/kde/kde-runtime/]
|-
| style="background-color:#EFEFEF;" | '''Easy Repository'''
| git clone kde:kde-runtime.git
|-
| style="background-color:#EFEFEF;" | '''Full Repository'''
| git clone git://anongit.kde.org/kde-runtime.git
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''Project Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http:// Project]
| style="background-color:#FF6666" |
| style="background-color:#FF6666" |
| Yes
| A library for
|}

== KActivities ==

API for using and interacting with Activities as a consumer, application adding information to them or as an activity manager.

{| border="1" cellpadding="5" cellspacing="0"
|-
| width="25%" style="background-color:#EFEFEF;" | '''Project Page'''
| width="75%" | [https://projects.kde.org/projects/kde/kdelibs/kactivities https://projects.kde.org/projects/kde/kdelibs/kactivities]
|-
| style="background-color:#EFEFEF;" | '''Easy Repository'''
| git clone kde:kactivities
|-
| style="background-color:#EFEFEF;" | '''Full Repository'''
| git clone git://anongit.kde.org/kactivities
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''Project Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http:// Project]
| style="background-color:#FF6666" |
| style="background-color:#FF6666" |
| Yes
| A library for
|}

== Kate ==

TODO: Does it belong here or Apps?

Kate is the text editor component for the KDE Development Platform.

{| border="1" cellpadding="5" cellspacing="0"
|-
| width="25%" style="background-color:#EFEFEF;" | '''Project Page'''
| width="75%" | [https://projects.kde.org/projects/kde/kdebase/kate https://projects.kde.org/projects/kde/kdebase/kate]
|-
| style="background-color:#EFEFEF;" | '''Easy Repository'''
| git clone kde:kate.git
|-
| style="background-color:#EFEFEF;" | '''Full Repository'''
| git clone git://anongit.kde.org/kate.git
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''Kate Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http:// Project]
| style="background-color:#FF6666" |
| style="background-color:#FF6666" |
| Yes
| A library for
|}

== Konsole ==

TODO: Does it belong here or Apps?

Konsole is the terminal emulator component for the KDE Development Platform.

{| border="1" cellpadding="5" cellspacing="0"
|-
| width="25%" style="background-color:#EFEFEF;" | '''Project Page'''
| width="75%" | [https://projects.kde.org/projects/kde/kdebase/konsole https://projects.kde.org/projects/kde/kdebase/konsole]
|-
| style="background-color:#EFEFEF;" | '''Easy Repository'''
| git clone kde:konsole.git
|-
| style="background-color:#EFEFEF;" | '''Full Repository'''
| git clone git://anongit.kde.org/konsole.git
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''Konsole Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http:// Project]
| style="background-color:#FF6666" |
| style="background-color:#FF6666" |
| Yes
| A library for
|}

== KDE SDK ==

The KDE SDK Module is not strictly speaking part of the KDE Development Platform, but it contains many useful tools and scripts that make developing KDE Software a lot easier and so is recommended to always be built or installed.

{| border="1" cellpadding="5" cellspacing="0"
|-
| width="25%" style="background-color:#EFEFEF;" | '''Project Page'''
| width="75%" | http://websvn.kde.org/trunk/KDE/kdesdk/
|-
| style="background-color:#EFEFEF;" | '''Easy Repository'''
| svn checkout svn://anonsvn.kde.org/home/kde/trunk/KDE/kdesdk/
|-
| style="background-color:#EFEFEF;" | '''Full Repository'''
| svn checkout svn://anonsvn.kde.org/home/kde/trunk/KDE/kdesdk/
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''KDE SDK Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http:// Project]
| style="background-color:#FF6666" |
| style="background-color:#FF6666" |
| Yes
| A library for
|}

Getting Started/Build/KDE Support

2012-03-18T16:11:27Z

Odysseus: /* Full Recipe */

{{warning|This page is yet to be reviewed for changes required by the migration to Git. Information and commands on this page may no longer be valid and should be used with care. Please see the [[Development/Git|KDE Git hub page]] for more details. }}

{{Template:I18n/Language Navigation Bar|Getting_Started/Build/KDE_Support}}

{{TutorialBrowser|
series=Getting Started|
name=Building KDE4 From Source/KDE Support|
pre=[[../Qt|Qt]]|
next=[[../KDE_Development_Platform|KDE Development Platform]]|
|
}}

== Introduction ==

The KDE Support module contains a number of KDE developed and supported packages that the main KDE Modules depend upon. Your distribution packages may be sufficient for these requirements when building a KDE stable branch, but Unstable may sometimes require the latest versions to be built from source.

Most KDE Support packages have now migrated to Git as separate modules and must be built individually, although some are still left in Subversion and can be built as a single unit. The modules are listed below in a rough dependency order.

=== Required Steps ===

You need to have completed the following steps:
* Set up your [[../Environment|Build Environment]]
* Selected your [[../Recipes|Build Recipes]]
* Installed the [[../Requirements|System Requirements]]
* Installed or Built [[../Qt|Qt and related requirements]]
* Understand the [[../Requirements#Definitions|Requirements Table format]]

== Requirements ==

The following table summarizes all the Projects contained in KDE Support and the versions required for building KDE Software. The optional/mandatory coloring is based on the requirements of the KDE Development Platform, the requirements for building other KDE Modules or Applications may vary.

{| border="1" cellpadding="5" cellspacing="0"
|+ '''Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http://projects.kde.org/projects/kdesupport/automoc Automoc]
|
|
| No
|
|-
| [http://projects.kde.org/projects/kdesupport/attica Attica]
|
|
| Yes
|
|-
| [http://projects.kde.org/projects/kdesupport/polkit-qt-1 Polkit Qt]
|
|
| Yes
|
|-
| [https://projects.kde.org/projects/kdesupport/strigi Strigi]
|
|
| Yes
|
|-
| [http://projects.kde.org/projects/kdesupport/soprano Soprano]
|
|
| Yes
|
|-
| [http://projects.kde.org/projects/kdesupport/akonadi Akonadi]
|
|
| Yes
|
|-
| [http://projects.kde.org/projects/kdesupport/cagibi Cagibi]
|
|
| Yes
|
|-
| [https://projects.kde.org/projects/kdesupport/phonon Phonon]
|
|
| Yes
|
|-
| [http://projects.kde.org/projects/kdesupport/prison Prison]
|
| style="background-color:#66FF66" | Any
| Yes
| A Qt based barcode library
|-
| Oxygen Icons
|
|
| No
|
|-
| QImageBlitz
|
|
| Yes
|
|-
| TagLib
|
|
| Yes
|
|-
| cpp2xml
|
|
| No
|
|}

== Template ==

Project is a

{| border="1" cellpadding="5" cellspacing="0"
|-
| width="25%" style="background-color:#EFEFEF;" | '''Project Page'''
| width="75%" | [http://projects.kde.org/projects/kdesupport/project http://projects.kde.org/projects/kdesupport/project]
|-
| style="background-color:#EFEFEF;" | '''Stable Version'''
|
|-
| style="background-color:#EFEFEF;" | '''Required By'''
|
|-
| style="background-color:#EFEFEF;" | '''Easy Repository'''
| git clone kde:project.git
|-
| style="background-color:#EFEFEF;" | '''Full Repository'''
| git clone git://anongit.kde.org/project.git
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''KDE Software Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http://projects.kde.org/projects/kdesupport/project Project]
| style="background-color:#66FF66;" |
| style="background-color:#66FF66;" |
| Yes
| A library
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''Project Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http:// Project]
| style="background-color:#FF6666" |
| style="background-color:#FF6666" |
| Yes
| A library for
|}

== Automoc ==

Automoc is a tool to automate Qt moc file creation. Automoc '''MUST''' be built first as other KDE Support Modules depend on it.

{| border="1" cellpadding="5" cellspacing="0"
|-
| width="25%" style="background-color:#EFEFEF;" | '''Project Page'''
| width="75%" | [http://projects.kde.org/projects/kdesupport/automoc http://projects.kde.org/projects/kdesupport/automoc]
|-
| style="background-color:#EFEFEF;" | '''Stable Version'''
| 0.9.88
|-
| style="background-color:#EFEFEF;" | '''Required By'''
| All KDE Modules and Projects using moc
|-
| style="background-color:#EFEFEF;" | '''Easy Repository'''
| git clone kde:automoc.git
|-
| style="background-color:#EFEFEF;" | '''Full Repository'''
| git clone git://anongit.kde.org/automoc.git
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''KDE Software Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http://projects.kde.org/projects/kdesupport/automoc Automoc]
| style="background-color:#FF6666;" |
| style="background-color:#FF6666;" |
| No
| A tool to automate Qt moc file creation.
|}

== Attica ==

Attica is a library for accessing the Open Collaboration Services.

{| border="1" cellpadding="5" cellspacing="0"
|-
| width="25%" style="background-color:#EFEFEF;" | '''Project Page'''
| width="75%" | [http://projects.kde.org/projects/kdesupport/attica http://projects.kde.org/projects/kdesupport/attica]
|-
| style="background-color:#EFEFEF;" | '''Stable Version'''
| 0.2.0
|-
| style="background-color:#EFEFEF;" | '''Required By'''
|
|-
| style="background-color:#EFEFEF;" | '''Easy Repository'''
| git clone kde:attica.git
|-
| style="background-color:#EFEFEF;" | '''Full Repository'''
| git clone git://anongit.kde.org/attica.git
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''KDE Software Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http://projects.kde.org/projects/kdesupport/attica Attica]
| style="background-color:#66FF66;" |
| style="background-color:#66FF66;" |
| Yes
| A library for accessing the Open Collaboration Services.
|}

== Polkit Qt==

Polkit Qt is a library for accessing the PolicyKit authorization framework.

{| border="1" cellpadding="5" cellspacing="0"
|-
| width="25%" style="background-color:#EFEFEF;" | '''Project Page'''
| width="75%" | [http://projects.kde.org/projects/kdesupport/polkit-qt-1 http://projects.kde.org/projects/kdesupport/polkit-qt-1]
|-
| style="background-color:#EFEFEF;" | '''Stable Version'''
| 0.99
|-
| style="background-color:#EFEFEF;" | '''Required By'''
|
|-
| style="background-color:#EFEFEF;" | '''Easy Repository'''
| git clone kde:polkit-qt-1.git
|-
| style="background-color:#EFEFEF;" | '''Full Repository'''
| git clone git://anongit.kde.org/polkit-qt-1.git
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''KDE Software Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http://projects.kde.org/projects/kdesupport/polkit-qt-1 PolKit Qt]
| style="background-color:#66FF66;" |
| style="background-color:#66FF66;" |
| Yes
| A library for accessing the PolicyKit authorization framework.
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''Polkit Qt Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http://www.freedesktop.org/wiki/Software/PolicyKit PolicyKit]
| style="background-color:#FF6666" | >= 0.98
| style="background-color:#FF6666" | >= 0.98
| Yes
| The PolicyKit authorization framework. PolicyKit 0.98 is recommended, but Polkit Qt will build with any version.
|}

== Strigi ==

Strigi is a library for indexing files. Note that Strigi has now been split into a number of separate Git sub-projects, but these can still be cloned and built as a single entity using the Strigi parent project.

{| border="1" cellpadding="5" cellspacing="0"
|-
| width="25%" style="background-color:#EFEFEF;" | '''Project Page'''
| width="75%" | [http://projects.kde.org/projects/kdesupport/strigi http://projects.kde.org/projects/kdesupport/strigi]
|-
| style="background-color:#EFEFEF;" | '''Stable Version'''
| 0.7.2
|-
| style="background-color:#EFEFEF;" | '''Required By'''
|
|-
| style="background-color:#EFEFEF;" | '''Easy Repository'''
| git clone kde:strigi
|-
| style="background-color:#EFEFEF;" | '''Full Repository'''
| git clone git://anongit.kde.org/strigi
|}

{{ warning|As of 2011-03-21: After cloning the Strigi parent project, you will have to run the ''change_to_development_git.sh'' script to pull in all sub projects.}}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''KDE Software Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http://projects.kde.org/projects/kdesupport/strigi Strigi]
| style="background-color:#66FF66;" |
| style="background-color:#66FF66;" |
| Yes
| A library for indexing files.
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''Project Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http://qt.nokia.com/ Qt]
| style="background-color:#FF6666" | >= 4.3.0
| style="background-color:#FF6666" | >= 4.3.0
| Yes
| The Qt development framework.
|-
| [http://www.zlib.net/ libz]
| style="background-color:#FF6666" |
| style="background-color:#FF6666" |
| Yes
| A library for zip file compression
|-
| [http://bzip.org/ libbz2]
| style="background-color:#FF6666" |
| style="background-color:#FF6666" |
| Yes
| A library for bzip2 file compression.
|-
| [http://xmlsoft.org/ libxml2]
| style="background-color:#FF6666" |
| style="background-color:#FF6666" |
| Yes
| A library for parsing XML
|-
| [http://clucene.sourceforge.net/ Clucene]
| style="background-color:#66FF66" | >=0.9.16a
| style="background-color:#66FF66" | >=0.9.16a
| Yes
| A high-performance indexing and searching API. Version 0.9.17 does '''not''' work.
|-
| [http://www.exiv2.org/ Exiv2]
| style="background-color:#66FF66" |
| style="background-color:#66FF66" |
| Yes
| A library to manage image metadata.
|-
| [http://www.ffmpeg.org/ FFMPEG]
| style="background-color:#66FF66" |
| style="background-color:#66FF66" |
| Yes
| A library for reading audio and video files.
|-
| [http://www.freedesktop.org/wiki/Software/dbus DBus]
| style="background-color:#66FF66" |
| style="background-color:#66FF66" |
| Yes
| A message bus system.
|-
| [http://oss.sgi.com/projects/fam/ FAM]
| style="background-color:#66FF66" |
| style="background-color:#66FF66" |
| Yes
| A tool for file system monitoring.
|-
| [http://logging.apache.org/log4cxx/index.html Log4cxx]
| style="background-color:#66FF66" |
| style="background-color:#66FF66" |
| Yes
| A logging framework for C++
|-
| [http://sourceforge.net/projects/cppunit/ CppUnit]
| style="background-color:#66FF66" |
| style="background-color:#66FF66" |
| Yes
| A C++ Unit Testing framework
|}

== Soprano ==

Soprano is a library for storing RDF data for the Nepomuk semantic desktop.

Please see the [http://projects.kde.org/projects/kdesupport/soprano Soprano project page] for details.

Soprano must be built '''BEFORE''' Akonadi.

Easy: git clone kde:soprano.git
Full: git clone git://anongit.kde.org/soprano.git

== Akonadi ==

Akonadi is a library for caching PIM data.

Please see the [http://projects.kde.org/projects/kdesupport/akonadi Akonadi project page] for details.

Akonadi must be built '''AFTER''' Soprano.

Easy: git clone kde:akonadi.git
Full: git clone git://anongit.kde.org/akonadi.git

== Cagibi ==

Cagibi is a cache/proxy daemon for SSDP, the discovery part of UPnP.

Please see the [http://projects.kde.org/projects/kdesupport/cagibi Cagibi project page] for details.

Easy: git clone kde:cagibi.git
Full: git clone git://anongit.kde.org/cagibi.git

== Qt Zeitgeist ==

Qt Zeitgeist is a QT wrapper for the Zeitgeist logging program.

Please see the [http://projects.kde.org/projects/kdesupport/libqtzeitgeist Qt Zeitgeist project page] for details.

Easy: git clone kde:libqtzeitgeist.git
Full: git clone git://anongit.kde.org/libqtzeitgeist.git

== Phonon ==

Phonon is a sound system abstraction layer. This is usually packaged with Qt, but the Phonon version from Qt is not recent enough for KDE sound to work so you will need to build the required version yourself.

Please see the [https://projects.kde.org/projects/kdesupport/phonon Phonon project page] for details.

You need to install this Phonon in the same location as Phonon from Qt i.e. in $QTDIR and '''NOT''' in $KDEDIR.

=== Easy Recipe ===

This recipe assumes you have set up the recommended KDE scripts, environment variables, and git configuration.

cd <your source root directory>
git clone kde:phonon.git
cd phonon
cb
cmake <path to your module source dir>
\ -DCMAKE_INSTALL_PREFIX=$QTDIR
\ -DCMAKE_BUILD_TYPE=debugfull
\ -DKDE4_BUILD_TESTS=TRUE
make
make install

Note that make install may require root access.

=== Full Recipe ===

This recipe assumes you are not using the recommended scripts and have properly set up your own environment.

cd <your source root directory>
git clone git://anongit.kde.org/phonon.git
cd <your build root directory, or the module source dir>
mkdir <your module build dir>
cd <your module build dir>
cmake <path to your module source dir>
\ -DCMAKE_INSTALL_PREFIX=$QTDIR
\ -DCMAKE_BUILD_TYPE=debugfull
make
make install

=== Backend ===

Building the main Phonon module is sufficient for building KDE. If you also want to play sound then you need to build a backend. Choose a suitable backend from those available below:

git clone git://anongit.kde.org/phonon-gstreamer.git
git clone git://anongit.kde.org/phonon-xine.git
git clone git://anongit.kde.org/phonon-directshow.git
git clone git://anongit.kde.org/phonon-mmf.git
git clone git://anongit.kde.org/phonon-quicktime.git
git clone git://anongit.kde.org/phonon-waveout.git

Note that DirectShow is for Windows only.

=== Troubleshooting ===

If you get an error like

designer: symbol lookup error: /path/to/kde/lib/kde4/plugins/phonon_backend/phonon_xine.so:
undefined symbol: _ZN6Phonon12PulseSupport11getInstanceEv

while running Qt Designer you need to:

rm $QTDIR/lib/libphonon.so.4

== Prison ==

Prison is a barcode library to enable optional barcode support in KDE Software. It was introduced in the KDE 4.7 Release Cycle.

{| border="1" cellpadding="5" cellspacing="0"
|-
| width="25%" | '''Project Page'''
| width="75%" | [http://projects.kde.org/projects/kdesupport/prison http://projects.kde.org/projects/kdesupport/prison]
|-
| '''Stable Version'''
| Unreleased
|-
| '''Required By'''
| No KDE Modules as yet
|-
| '''Easy Repository'''
| git clone kde:prison.git
|-
| '''Full Repository'''
| git clone git://anongit.kde.org/prison.git
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''KDE Software Build Requirements'''
|-
! width="20%" | Requirement
! width="15%" | Stable Requires
! width="15%" | Unstable Requires
! width="10%" | Devel Pkgs?
! width="40%" | Details
|-
| [http://projects.kde.org/projects/kdesupport/prison Prison]
|
| style="background-color:#6ECFFF;" | Any
| Yes
| A Qt based barcode library
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''Prison Build Requirements'''
|-
! width="20%" | Requirement
! width="15%" | Stable Requires
! width="15%" | Unstable Requires
! width="10%" | Devel Pkgs?
! width="40%" | Details
|-
| [http://fukuchi.org/works/qrencode/index.en.html QRencode]
|
| style="background-color:#FF6E6E;" | Any
| Yes
| A library for reading and writing QR Code barcodes
|-
| [http://www.libdmtx.org/ Dmtx]
|
| style="background-color:#FF6E6E;" | Any
| Yes
| A library for reading and writing Data Matrix 2D barcodes
|}

== kdesupport svn module ==

A number of kdesupport packages are still in svn:

* oxygen-icons
* qimageblitz - for building kde-workspace
* taglib
* taglib-extras
* cpp2xml
* twine - for building kdebindings
* emerge - for building kde on windows

These packages can be checked out and built together with a single recipe.

Note that QCA lives in kdesupport svn but is not built by default. It is recommended that you use your system QCA packages and only checkout the kdesupport svn version if you are going to develop QCA.

=== Easy Recipe ===

This recipe assumes you have set up the recommended KDE scripts, environment variables, and git configuration.

cd <your source root directory>
svn checkout svn://anonsvn.kde.org/home/kde/trunk/kdesupport/
cd kdesupport
kdebuild

=== Full Recipe ===

This recipe assumes you are not using the recommended scripts and have properly set up your own environment.

cd <your source root directory>
svn checkout svn://anonsvn.kde.org/home/kde/trunk/kdesupport/
cd <your build root directory, or the module source dir>
mkdir <your module build dir>
cd <your module build dir>
cmake <path to your module source dir>
\ -DCMAKE_INSTALL_PREFIX=$KDEDIR
\ -DCMAKE_BUILD_TYPE=debugfull
\ -DKDE4_BUILD_TESTS=TRUE
make
make install

== Troubleshooting ==

If you get a message related to
target libQtTest.so not found
you may need to recompile qt-kde. This time you should take out
-nomake demos -nomake examples
from the configure command, so that Qt generates library QtTest.

If you get
CMake Error: Qt qmake not found!
Then:
1) uncomment Qt section in .bashrc script (QTDIR, QT_PLUGINS_DIR,
PKG_CONFIG_PATH variable settings).
2) source ~/.bashrc
3) cd && cd qt-kde
4) make confclean
5) repeat steps for installing Qt (from ./configure line).
6) retry building kdesupport

= Next Step =

Once all the KDE Support requirements have been installed it is time to install the [[../KDE_Development_Platform|KDE Development Platform]]

Archive:Getting Started/Build/Qt

2012-03-17T22:42:15Z

Odysseus: /* DBusMenu-Qt */

Development/Git/Recipes

2011-11-06T18:06:38Z

Odysseus: /* Working with stable branches */

== Git Recipes ==

Brief recipes for common use cases.

=== Cloning a Repository ===

To clone a local copy of a KDE Git repository, find the repository on http://projects.kde.org/projects, choose the project, choose the Repository tab and copy the git clone command displayed:

git clone git://anongit.kde.org/<repository-name>

Note this clone will be read-only and you will not be able to push from it.

Alternatively, if you have the standard [[Development/Git/Configuration|KDE Git configuration]] and know the name of the repository simply do:

git clone kde:<repository-name>

This will automatically set the repository up to have push access.

=== Working with existing remote branches ===

Remote branches are branches created on the main KDE repository. These may be a stable branch that you need to do bugfixes on, i.e. the 4.6 release, or a feature branch based on master.

To see what local and remote branches exist:
git branch -a

Create a local branch that tracks a remote branch:
git branch --track <local-branch> <remote-branch>
git checkout <local-branch>

When you want to add your commits to the remote branch, first update your local to the current remote state, then push your commits:
git pull --rebase
git push origin <local-branch>:<remote-branch>

=== Working with stable branches ===

The remote stable branches are named as follows:

origin/KDE/4.6

To set up a local stable branch to track the remote stable branch:

git branch --track KDE/4.6 origin/KDE/4.6
git checkout KDE/4.6

To then push changes to the remote stable branch:

git push origin KDE/4.6:KDE/4.6

=== Creating / Deleting Remote Branches ===

To create a new remote branch simply push your current branch to it:

git push origin <local-branch>:<remote-branch>

To delete a remote branch is a little obscure:

git push origin :<remote-branch>

=== Tracking Branches ===

To create a new branch that tracks an existing local or remote branch:

git branch --track <new-branch> <existing-branch>

To change the branch the current branch is tracking to a different local or remote branch:

git branch --set-upstream <existing-branch> <new-upstream-branch>

=== Cherry Picking ===

Cherry picking is a way to copy a single commit from any local or remote branch to your current local branch. You can even add ''any'' remote repository you want to your local clone to cherry-pick from.

git cherry-pick <original-commit>

When cherry picking between stable and unstable branches, ''always'' use the following form:

git cherry-pick -e -x <original-commit>

Common Options:

'''-e''' will allow you to edit the commit message to add any extra details and to change the BUG/CCBUG/FIXED-IN messages.

'''-x''' will automatically add the original commit number to the end of the commit message to enable better tracing and to simplify merging. Only do this if the original commit was already published in a public repository, e.g. your are forward porting or back porting the patch.

'''-n''' will cherry-pick the changes but not commit them to the new branch. This is very useful if you need to do further work on a commit.

=== Interactive Rebasing ===

If you have many commits in a branch that you want to clean up before pushing to the central repository, then you can use interactive rebasing to merge, split, delete, re-order or edit them.

To work with all commits to a branch:

git rebase -i <parent-branch>

where <parent-branch> is the branch you want to rebase onto. This is usually the branch that you based the original local branch off or are remotely tracking, but can be any branch you want.

To work with just the last n commits you made to a branch:

git rebase -i HEAD^n

HEAD^ is the terminology for saying "commit prior to head". HEAD~ works too. HEAD^^ would indicate 2 commits back, and so forth.

See http://book.git-scm.com/4_interactive_rebasing.html for full details.

=== Viewing What You've Changed ===

To see the difference between your tracked but unstaged changes and the current branch (including your not-yet-pushed commits)

git diff
git diff <filename>

To see the difference between your staged changes and the current branch (including your not-yet-pushed commits):

git diff --staged
git diff --staged <filename>

To see a list of commits to a branch:

git log

To see the details and diff for a commit

git show <commit>

=== Stashing Changes ===

If you have changes you don't wish to commit but don't want to lose either while you do something else, you can temporarily 'stash' the changes away. This could be some frequently used debug code,or just some work in progress you need to move to another branch without committing. If the code is just WIP for the current branch we recommend using an interim commit instead.

The stash is a temporary store that holds a stack of uncommitted changes at a repository level. Commands given below work by default with the stash at the top of the stack, or you can optionally provide the stack reference.

To store your current changes at the top of the stash stack:

git stash <optional comment>

For example:

git stash "My debug code"

To see all your stashed items in the stash stack:

git stash list

This will show something like:

stash@{0}: WIP on master: 6ebd0e2... My debug code
stash@{1}: WIP on master: 9cc0589... My stashed changes

To see the details of an individual stash:

git stash show <optional stash ref>

To see the stash at the top of the stack:

git stash show

To see the second item from top:

git stash show stash@{1}

To restore a stash while keeping a copy in the stack:

git stash apply <optional stash ref>

To restore a stash and remove it from the stack:

git stash pop <optional stash ref>

To remove a single stash from the stack without applying it:

git stash drop <optional stash ref>

To clear out your entire stash stack:

git stash clear

For more details see:

http://www.kernel.org/pub/software/scm/git/docs/git-stash.html
http://book.git-scm.com/4_stashing.html

Archive:Getting Started/Build/Qt

2011-09-07T18:47:27Z

Odysseus: /* Qt */

Projects/Marble

2011-09-01T18:26:12Z

Odysseus: /* Mapping Coordination */

{{Template:I18n/Language Navigation Bar|Projects/Marble}}

[[Image:Marble_logo.png]]

== About Marble ==
;[[/Devices_and_Use_Cases|Devices and Use Cases]]
;[[/FAQ|Marble FAQ]]

== Success Stories: 3rd party applications using the Marble Library==
;[[/MarbleUsedBy|Software that makes use of Marble]]

== Tutorials: How to use the Marble Widget in your application ==
;[[/MarbleDesigner|with Qt Designer]]
;[[/MarbleWindows|On Windows, with Qt Creator/Qt Designer]]
;[[/MarbleCPlusPlus|with C++]]
;[[/MarblePython|with Python]]

;[[/MarbleDBus|via a shell script]]

== How to become a Marble developer ("Marblehead") ==

=== So you are new to Marble development ... ===

<b>Welcome!</b>

Here you'll get all the information you need to start Marble development:

;[[/GoMarble|How to become a Marble Developer]]

== Compiling Marble ==
;[[/LinuxCompiling|Compiling on Linux]]
;[[/WindowsCompiling|Compiling on Windows]]
;[[/MaemoEnvironment|Compiling on Maemo]]
;[[/MeeGoEnvironment|Compiling on MeeGo]]
;[[/MacCompiling|Compiling on Mac OS]]
;[[/QtCreator|Setting up QtCreator for Marble Development]]

== Packaging Marble ==

;[[/NewMarbleMoldules|New Marble Modules]] (future packaging advice)

Here is some advice about how packaging is supposed to happen on the various platforms that are supported.

;[[/LinuxPackaging|Packaging for Linux]]
;[[/WindowsPackaging|Packaging for Windows]]
;[[/MaemoPackaging|Packaging for Maemo]]
;[[/MeeGoPackaging|Packaging for MeeGo]]
;[[/MacPackaging|Packaging for Mac]]

== Tools for Marble ==

Here are some tools and checks that are performed on marble code:
;[https://bugs.kde.org/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=marble&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&cmdtype=doit&order=Importance Marble Open Bugs]
;[http://reviewboard.kde.org/groups/marble/ Review Board]
;[http://api.kde.org/4.x-api/kdeedu-apidocs/marble/html/index.html API Docs (KDE Trunk)]
;[http://www.englishbreakfastnetwork.org/apidocs/apidox-kde-4.x/kdeedu-marble.html APIDOX reports]
;[http://www.englishbreakfastnetwork.org/krazy/reports/kde-4.x/kdeedu/marble/index.html Krazy reports]

== Programming Coordination ==

Here are a few links to various issues we are working on:
;[[/Gsoc2010| Gsoc Students projects 2010]]
;[[/GsocGit| Use of git(orious) for GSOC]]
;[[/TODO|TODO list]]
;[[/MaemoTODO|Maemo specific TODO list]]

;[[/GSoC2011| GSoC Students' projects 2011]]
;[http://community.kde.org/SoCiS/2011/Ideas#Marble_Virtual_Globe ESA SoCIS 2011 ideas]

=== Translation ===
;[[/MapTranslation|Map Translation]]
;[[/UiTranslation|UI Translation]]

=== User Interface ===
;[[/Mockups|Mockups]]
;[[/IconStatus|Icon Status]]

=== Texture Mapping ===
;[[/TextureNG|Texture Mapping]]

=== GeoData Library / KML ===
The base classes to manipulate geographic data
;[[/GeoData|GeoData Presentation]]
;[[/GeoData/GeoDataUse|Use cases for GeoData classes]]
;[http://websvn.kde.org/*checkout*/trunk/KDE/kdeedu/marble/src/lib/geodata/data/README.html GeoData API Description]
;[[/GeoData/GeoDataParsing|Parsing GeoData]]
;[[/GeoData/GeoDataWriter|Writing GeoData]]
;[[/GeoData/PointerVsImplicitShare|Pointer vs. Implicit Share]]

;[[/KMLStatus|KML Status]]
;[[/GPXStatus|GPX Status]]

Using GeoData:
;[[/FileManagement|File Management]]
;[[/Placemark|Placemarks Management]]
;[[/ModelView|Review of Model-View use in marble]]

=== Geo Graphics View ===
;[[/GeoGraphicsViewOverview|Overview of the GeoGraphicsView]]
;[[/GraphicsViewGeoParser| Interaction between GeoData and GeoGraphicsView]]

=== GeoPainter / DGML ===
;[[/GeoPainter|GeoPainter]]
;[[/Dgml|DGML]]

=== Plugin Interfaces ===
;[[/Plugins|Plugin interfaces]]

=== Marble Runner ===
;[[/CoordinateRunner|Coordinate Runner]]
;[[/OsmNameFinderRunner|OSM Runner]]
;[[/RunnerHOWTO|Runner HOWTO]]

=== Online Services ===
;[[/OnlineServices|Creating new Online Services]]
;[[/ListOfPossibleOnlineServices|List of possible Online Services]]

=== Projections ===
;[[/WinkelIii|Winkel III]]
;[[/RobinsonProjection|Robinson projection]]
[http://www.radicalcartography.net/?projectionref A little overview of map projections]

=== Tile Download ===
;[[/TileDownload|Tile Download]]

=== Documentation ===
;[[/CustomMaps|How to customize maps]]
;[[/MarblesSecrets|Marble's Secrets]]
;[[/ProxyConnection|How to use the Proxy]]

=== GeoClue / GPS ===
;[[/GeoClue|GeoClue support in Marble]]

=== XDG Base Directory Specification ===
;[[/xdg|XDG Base Directory Specification]]

== Mapping Coordination ==
Possible maps we could use:
* [http://www.unearthedoutdoors.net/global_data/true_marble/download TrueMarble Global 250m images]
* [http://onearth.jpl.nasa.gov/ OnEarth NASA satellite images]
* [http://worldwindcentral.com/wiki/Add-on:ZoomIt! ZoomIt! (in parts proprietary)]
* [http://sos.noaa.gov/datasets/ NOAA Science on a Sphere]
* [http://efele.net/maps/tz/world/ Olsen Time Zone map in Shapefile format]. Public Domain. Scripted to generate from current tz file.

=== Natural Earth Vector Map ===
;[[/NaturalEarth|A proposal to use the Natural Earth vector map]]

=== Documentation ===
;[[/HistoricalMaps|How to create Historical Maps]]
;[[/CustomMaps|How to create Custom Maps]]

;[[/PalaeoMaps|Global Palaeogeography]]

== Routing ==
;[[/OnlineRoutingImplementation|Implementation of Online-Routing]]
;[[/MaemoOfflineRouting|Installation of Marble and Gosmore on Maemo]]
;[[/RoutingRoadmap|Routing Roadmap]]
;[[/RoutingInstructions|Routing Instructions]]

== valgrind ==
if you want to fix memory leaks, you can run valgrind with:

valgrind --leak-check=full --track-origins=yes --num-callers=30 marble 2>&1 | tee MARBLE_MEMCHECK

== Meetings ==
Summaries and logs of scheduled Marble meetings can be found on the following pages:
;[[/MarbleMeeting20081029|Wednesday Nov. 10th, 2008]]

;[[/MarbleMeeting20101107|Marble Weekend Sprint, Nov. 5-7]]

Development/Git/Recipes

2011-08-30T19:16:23Z

Odysseus: /* Working with existing remote branches */

== Git Recipes ==

Brief recipes for common use cases.

=== Cloning a Repository ===

To clone a local copy of a KDE Git repository, find the repository on http://projects.kde.org/projects, choose the project, choose the Repository tab and copy the git clone command displayed:

git clone git://anongit.kde.org/<repository-name>

Note this clone will be read-only and you will not be able to push from it.

Alternatively, if you have the standard [[Development/Git/Configuration|KDE Git configuration]] and know the name of the repository simply do:

git clone kde:<repository-name>

This will automatically set the repository up to have push access.

=== Working with existing remote branches ===

Remote branches are branches created on the main KDE repository. These may be a stable branch that you need to do bugfixes on, i.e. the 4.6 release, or a feature branch based on master.

To see what local and remote branches exist:
git branch -a

Create a local branch that tracks a remote branch:
git branch --track <local-branch> <remote-branch>
git checkout <local-branch>

When you want to add your commits to the remote branch, first update your local to the current remote state, then push your commits:
git pull --rebase
git push origin <local-branch>:<remote-branch>

=== Working with stable branches ===

For kdelibs, kdepimlibs, kde-runtime, kate, konsole and kde-workspace, the remote stable branches are named as follows:

origin/KDE/4.6

For these modules, to set up a local stable branch to track the remote stable branch:

git branch --track KDE/4.6 origin/KDE/4.6
git checkout KDE/4.6

To then push changes to the remote stable branch:

git push origin KDE/4.6:KDE/4.6

In other projects the remote stable branches are named as follows:

origin/4.6

For these modules, to set up a local stable branch to track the remote stable branch:

git branch --track 4.6 origin/4.6
git checkout 4.6

To then push changes to the remote stable branch:

git push origin 4.6:4.6

=== Creating / Deleting Remote Branches ===

To create a new remote branch simply push your current branch to it:

git push origin <local-branch>:<remote-branch>

To delete a remote branch is a little obscure:

git push origin :<remote-branch>

=== Tracking Branches ===

To create a new branch that tracks an existing local or remote branch:

git branch --track <new-branch> <existing-branch>

To change the branch the current branch is tracking to a different local or remote branch:

git branch --set-upstream <existing-branch> <new-upstream-branch>

=== Cherry Picking ===

Cherry picking is a way to copy a single commit from any local or remote branch to your current local branch. You can even add ''any'' remote repository you want to your local clone to cherry-pick from.

git cherry-pick <original-commit>

When cherry picking between stable and unstable branches, ''always'' use the following form:

git cherry-pick -e -x <original-commit>

Common Options:

'''-e''' will allow you to edit the commit message to add any extra details and to change the BUG/CCBUG/FIXED-IN messages.

'''-x''' will automatically add the original commit number to the end of the commit message to enable better tracing and to simplify merging. Only do this if the original commit was already published in a public repository, e.g. your are forward porting or back porting the patch.

'''-n''' will cherry-pick the changes but not commit them to the new branch. This is very useful if you need to do further work on a commit.

=== Interactive Rebasing ===

If you have many commits in a branch that you want to clean up before pushing to the central repository, then you can use interactive rebasing to merge, split, delete, re-order or edit them.

To work with all commits to a branch:

git rebase -i <parent-branch>

where <parent-branch> is the branch you want to rebase onto. This is usually the branch that you based the original local branch off or are remotely tracking, but can be any branch you want.

To work with just the last n commits you made to a branch:

git rebase -i HEAD^n

HEAD^ is the terminology for saying "commit prior to head". HEAD~ works too. HEAD^^ would indicate 2 commits back, and so forth.

See http://book.git-scm.com/4_interactive_rebasing.html for full details.

=== Viewing What You've Changed ===

To see the difference between your tracked but unstaged changes and the current branch (including your not-yet-pushed commits)

git diff
git diff <filename>

To see the difference between your staged changes and the current branch (including your not-yet-pushed commits):

git diff --staged
git diff --staged <filename>

To see a list of commits to a branch:

git log

To see the details and diff for a commit

git show <commit>

=== Stashing Changes ===

If you have changes you don't wish to commit but don't want to lose either while you do something else, you can temporarily 'stash' the changes away. This could be some frequently used debug code,or just some work in progress you need to move to another branch without committing. If the code is just WIP for the current branch we recommend using an interim commit instead.

The stash is a temporary store that holds a stack of uncommitted changes at a repository level. Commands given below work by default with the stash at the top of the stack, or you can optionally provide the stack reference.

To store your current changes at the top of the stash stack:

git stash <optional comment>

For example:

git stash "My debug code"

To see all your stashed items in the stash stack:

git stash list

This will show something like:

stash@{0}: WIP on master: 6ebd0e2... My debug code
stash@{1}: WIP on master: 9cc0589... My stashed changes

To see the details of an individual stash:

git stash show <optional stash ref>

To see the stash at the top of the stack:

git stash show

To see the second item from top:

git stash show stash@{1}

To restore a stash while keeping a copy in the stack:

git stash apply <optional stash ref>

To restore a stash and remove it from the stack:

git stash pop <optional stash ref>

To remove a single stash from the stack without applying it:

git stash drop <optional stash ref>

To clear out your entire stash stack:

git stash clear

For more details see:

http://www.kernel.org/pub/software/scm/git/docs/git-stash.html
http://book.git-scm.com/4_stashing.html

Development/Git/Recipes

2011-08-30T19:14:41Z

Odysseus: /* Cherry Picking */

== Git Recipes ==

Brief recipes for common use cases.

=== Cloning a Repository ===

To clone a local copy of a KDE Git repository, find the repository on http://projects.kde.org/projects, choose the project, choose the Repository tab and copy the git clone command displayed:

git clone git://anongit.kde.org/<repository-name>

Note this clone will be read-only and you will not be able to push from it.

Alternatively, if you have the standard [[Development/Git/Configuration|KDE Git configuration]] and know the name of the repository simply do:

git clone kde:<repository-name>

This will automatically set the repository up to have push access.

=== Working with existing remote branches ===

Remote branches are branches created on the main KDE repository. These may be a stable branch that you need to do bugfixes on, i.e. the 4.6 release, or a feature branch based on master.

To see what local and remote branches exist:
git branch -a

Create a local branch that tracks a remote branch:
git branch --track <local-branch> <remote-branch>
git checkout <local-branch>

When you want to add your commits to the local branch, first update your local to the current remote state, then push your commits:
git pull --rebase
git push origin <local-branch>:<remote-branch>

=== Working with stable branches ===

For kdelibs, kdepimlibs, kde-runtime, kate, konsole and kde-workspace, the remote stable branches are named as follows:

origin/KDE/4.6

For these modules, to set up a local stable branch to track the remote stable branch:

git branch --track KDE/4.6 origin/KDE/4.6
git checkout KDE/4.6

To then push changes to the remote stable branch:

git push origin KDE/4.6:KDE/4.6

In other projects the remote stable branches are named as follows:

origin/4.6

For these modules, to set up a local stable branch to track the remote stable branch:

git branch --track 4.6 origin/4.6
git checkout 4.6

To then push changes to the remote stable branch:

git push origin 4.6:4.6

=== Creating / Deleting Remote Branches ===

To create a new remote branch simply push your current branch to it:

git push origin <local-branch>:<remote-branch>

To delete a remote branch is a little obscure:

git push origin :<remote-branch>

=== Tracking Branches ===

To create a new branch that tracks an existing local or remote branch:

git branch --track <new-branch> <existing-branch>

To change the branch the current branch is tracking to a different local or remote branch:

git branch --set-upstream <existing-branch> <new-upstream-branch>

=== Cherry Picking ===

Cherry picking is a way to copy a single commit from any local or remote branch to your current local branch. You can even add ''any'' remote repository you want to your local clone to cherry-pick from.

git cherry-pick <original-commit>

When cherry picking between stable and unstable branches, ''always'' use the following form:

git cherry-pick -e -x <original-commit>

Common Options:

'''-e''' will allow you to edit the commit message to add any extra details and to change the BUG/CCBUG/FIXED-IN messages.

'''-x''' will automatically add the original commit number to the end of the commit message to enable better tracing and to simplify merging. Only do this if the original commit was already published in a public repository, e.g. your are forward porting or back porting the patch.

'''-n''' will cherry-pick the changes but not commit them to the new branch. This is very useful if you need to do further work on a commit.

=== Interactive Rebasing ===

If you have many commits in a branch that you want to clean up before pushing to the central repository, then you can use interactive rebasing to merge, split, delete, re-order or edit them.

To work with all commits to a branch:

git rebase -i <parent-branch>

where <parent-branch> is the branch you want to rebase onto. This is usually the branch that you based the original local branch off or are remotely tracking, but can be any branch you want.

To work with just the last n commits you made to a branch:

git rebase -i HEAD^n

HEAD^ is the terminology for saying "commit prior to head". HEAD~ works too. HEAD^^ would indicate 2 commits back, and so forth.

See http://book.git-scm.com/4_interactive_rebasing.html for full details.

=== Viewing What You've Changed ===

To see the difference between your tracked but unstaged changes and the current branch (including your not-yet-pushed commits)

git diff
git diff <filename>

To see the difference between your staged changes and the current branch (including your not-yet-pushed commits):

git diff --staged
git diff --staged <filename>

To see a list of commits to a branch:

git log

To see the details and diff for a commit

git show <commit>

=== Stashing Changes ===

If you have changes you don't wish to commit but don't want to lose either while you do something else, you can temporarily 'stash' the changes away. This could be some frequently used debug code,or just some work in progress you need to move to another branch without committing. If the code is just WIP for the current branch we recommend using an interim commit instead.

The stash is a temporary store that holds a stack of uncommitted changes at a repository level. Commands given below work by default with the stash at the top of the stack, or you can optionally provide the stack reference.

To store your current changes at the top of the stash stack:

git stash <optional comment>

For example:

git stash "My debug code"

To see all your stashed items in the stash stack:

git stash list

This will show something like:

stash@{0}: WIP on master: 6ebd0e2... My debug code
stash@{1}: WIP on master: 9cc0589... My stashed changes

To see the details of an individual stash:

git stash show <optional stash ref>

To see the stash at the top of the stack:

git stash show

To see the second item from top:

git stash show stash@{1}

To restore a stash while keeping a copy in the stack:

git stash apply <optional stash ref>

To restore a stash and remove it from the stack:

git stash pop <optional stash ref>

To remove a single stash from the stack without applying it:

git stash drop <optional stash ref>

To clear out your entire stash stack:

git stash clear

For more details see:

http://www.kernel.org/pub/software/scm/git/docs/git-stash.html
http://book.git-scm.com/4_stashing.html

Development/Git/Recipes

2011-08-30T19:11:44Z

Odysseus: /* Interactive Rebasing */

== Git Recipes ==

Brief recipes for common use cases.

=== Cloning a Repository ===

To clone a local copy of a KDE Git repository, find the repository on http://projects.kde.org/projects, choose the project, choose the Repository tab and copy the git clone command displayed:

git clone git://anongit.kde.org/<repository-name>

Note this clone will be read-only and you will not be able to push from it.

Alternatively, if you have the standard [[Development/Git/Configuration|KDE Git configuration]] and know the name of the repository simply do:

git clone kde:<repository-name>

This will automatically set the repository up to have push access.

=== Working with existing remote branches ===

Remote branches are branches created on the main KDE repository. These may be a stable branch that you need to do bugfixes on, i.e. the 4.6 release, or a feature branch based on master.

To see what local and remote branches exist:
git branch -a

Create a local branch that tracks a remote branch:
git branch --track <local-branch> <remote-branch>
git checkout <local-branch>

When you want to add your commits to the local branch, first update your local to the current remote state, then push your commits:
git pull --rebase
git push origin <local-branch>:<remote-branch>

=== Working with stable branches ===

For kdelibs, kdepimlibs, kde-runtime, kate, konsole and kde-workspace, the remote stable branches are named as follows:

origin/KDE/4.6

For these modules, to set up a local stable branch to track the remote stable branch:

git branch --track KDE/4.6 origin/KDE/4.6
git checkout KDE/4.6

To then push changes to the remote stable branch:

git push origin KDE/4.6:KDE/4.6

In other projects the remote stable branches are named as follows:

origin/4.6

For these modules, to set up a local stable branch to track the remote stable branch:

git branch --track 4.6 origin/4.6
git checkout 4.6

To then push changes to the remote stable branch:

git push origin 4.6:4.6

=== Creating / Deleting Remote Branches ===

To create a new remote branch simply push your current branch to it:

git push origin <local-branch>:<remote-branch>

To delete a remote branch is a little obscure:

git push origin :<remote-branch>

=== Tracking Branches ===

To create a new branch that tracks an existing local or remote branch:

git branch --track <new-branch> <existing-branch>

To change the branch the current branch is tracking to a different local or remote branch:

git branch --set-upstream <existing-branch> <new-upstream-branch>

=== Cherry Picking ===

Cherry picking is a way to copy a single commit from any local or remote branch to your current local branch.

When cherry picking between stable and unstable branches, use the following form:

git cherry-pick -e -x <original-commit>

Note you can add ''any'' remote repository to your local clone if cherry-pick from.

;Common Options

'''-e''' will allow you to edit the commit message to add any extra details and to change the BUG/CCBUG/FIXED-IN messages.

'''-x''' will automatically add the original commit number to the end of the commit message to enable better tracing and to simplify merging. Only do this if the original commit was already published in a public repository, e.g. your are forward porting or back porting the patch.

'''-n''' will cherry-pick the changes but not commit them to the new branch. This is very useful if you need to do further work on a commit.

=== Interactive Rebasing ===

If you have many commits in a branch that you want to clean up before pushing to the central repository, then you can use interactive rebasing to merge, split, delete, re-order or edit them.

To work with all commits to a branch:

git rebase -i <parent-branch>

where <parent-branch> is the branch you want to rebase onto. This is usually the branch that you based the original local branch off or are remotely tracking, but can be any branch you want.

To work with just the last n commits you made to a branch:

git rebase -i HEAD^n

HEAD^ is the terminology for saying "commit prior to head". HEAD~ works too. HEAD^^ would indicate 2 commits back, and so forth.

See http://book.git-scm.com/4_interactive_rebasing.html for full details.

=== Viewing What You've Changed ===

To see the difference between your tracked but unstaged changes and the current branch (including your not-yet-pushed commits)

git diff
git diff <filename>

To see the difference between your staged changes and the current branch (including your not-yet-pushed commits):

git diff --staged
git diff --staged <filename>

To see a list of commits to a branch:

git log

To see the details and diff for a commit

git show <commit>

=== Stashing Changes ===

If you have changes you don't wish to commit but don't want to lose either while you do something else, you can temporarily 'stash' the changes away. This could be some frequently used debug code,or just some work in progress you need to move to another branch without committing. If the code is just WIP for the current branch we recommend using an interim commit instead.

The stash is a temporary store that holds a stack of uncommitted changes at a repository level. Commands given below work by default with the stash at the top of the stack, or you can optionally provide the stack reference.

To store your current changes at the top of the stash stack:

git stash <optional comment>

For example:

git stash "My debug code"

To see all your stashed items in the stash stack:

git stash list

This will show something like:

stash@{0}: WIP on master: 6ebd0e2... My debug code
stash@{1}: WIP on master: 9cc0589... My stashed changes

To see the details of an individual stash:

git stash show <optional stash ref>

To see the stash at the top of the stack:

git stash show

To see the second item from top:

git stash show stash@{1}

To restore a stash while keeping a copy in the stack:

git stash apply <optional stash ref>

To restore a stash and remove it from the stack:

git stash pop <optional stash ref>

To remove a single stash from the stack without applying it:

git stash drop <optional stash ref>

To clear out your entire stash stack:

git stash clear

For more details see:

http://www.kernel.org/pub/software/scm/git/docs/git-stash.html
http://book.git-scm.com/4_stashing.html

Development/Git/Recipes

2011-08-30T19:09:13Z

Odysseus: /* Viewing What You've Changed */

== Git Recipes ==

Brief recipes for common use cases.

=== Cloning a Repository ===

To clone a local copy of a KDE Git repository, find the repository on http://projects.kde.org/projects, choose the project, choose the Repository tab and copy the git clone command displayed:

git clone git://anongit.kde.org/<repository-name>

Note this clone will be read-only and you will not be able to push from it.

Alternatively, if you have the standard [[Development/Git/Configuration|KDE Git configuration]] and know the name of the repository simply do:

git clone kde:<repository-name>

This will automatically set the repository up to have push access.

=== Working with existing remote branches ===

Remote branches are branches created on the main KDE repository. These may be a stable branch that you need to do bugfixes on, i.e. the 4.6 release, or a feature branch based on master.

To see what local and remote branches exist:
git branch -a

Create a local branch that tracks a remote branch:
git branch --track <local-branch> <remote-branch>
git checkout <local-branch>

When you want to add your commits to the local branch, first update your local to the current remote state, then push your commits:
git pull --rebase
git push origin <local-branch>:<remote-branch>

=== Working with stable branches ===

For kdelibs, kdepimlibs, kde-runtime, kate, konsole and kde-workspace, the remote stable branches are named as follows:

origin/KDE/4.6

For these modules, to set up a local stable branch to track the remote stable branch:

git branch --track KDE/4.6 origin/KDE/4.6
git checkout KDE/4.6

To then push changes to the remote stable branch:

git push origin KDE/4.6:KDE/4.6

In other projects the remote stable branches are named as follows:

origin/4.6

For these modules, to set up a local stable branch to track the remote stable branch:

git branch --track 4.6 origin/4.6
git checkout 4.6

To then push changes to the remote stable branch:

git push origin 4.6:4.6

=== Creating / Deleting Remote Branches ===

To create a new remote branch simply push your current branch to it:

git push origin <local-branch>:<remote-branch>

To delete a remote branch is a little obscure:

git push origin :<remote-branch>

=== Tracking Branches ===

To create a new branch that tracks an existing local or remote branch:

git branch --track <new-branch> <existing-branch>

To change the branch the current branch is tracking to a different local or remote branch:

git branch --set-upstream <existing-branch> <new-upstream-branch>

=== Cherry Picking ===

Cherry picking is a way to copy a single commit from any local or remote branch to your current local branch.

When cherry picking between stable and unstable branches, use the following form:

git cherry-pick -e -x <original-commit>

Note you can add ''any'' remote repository to your local clone if cherry-pick from.

;Common Options

'''-e''' will allow you to edit the commit message to add any extra details and to change the BUG/CCBUG/FIXED-IN messages.

'''-x''' will automatically add the original commit number to the end of the commit message to enable better tracing and to simplify merging. Only do this if the original commit was already published in a public repository, e.g. your are forward porting or back porting the patch.

'''-n''' will cherry-pick the changes but not commit them to the new branch. This is very useful if you need to do further work on a commit.

=== Interactive Rebasing ===

If you have many commits in a branch that you want to clean up before pushing to the central repository, then you can use interactive rebasing to merge, split, delete, re-order or edit them.

To work with all commits to a branch:

git rebase -i <parent-branch>

where <parent-branch> is the branch you want to rebase onto. This is usually the branch that you based the original local branch off or are remotely tracking, but can be any branch you want.

To work with just the last x commits you made to a branch:

git rebase -i HEAD^x

HEAD^ is the terminology for saying "commit prior to head". HEAD~ works too. HEAD^^ would indicate 2 commits back, and so forth.

See http://book.git-scm.com/4_interactive_rebasing.html for full details.

=== Viewing What You've Changed ===

To see the difference between your tracked but unstaged changes and the current branch (including your not-yet-pushed commits)

git diff
git diff <filename>

To see the difference between your staged changes and the current branch (including your not-yet-pushed commits):

git diff --staged
git diff --staged <filename>

To see a list of commits to a branch:

git log

To see the details and diff for a commit

git show <commit>

=== Stashing Changes ===

If you have changes you don't wish to commit but don't want to lose either while you do something else, you can temporarily 'stash' the changes away. This could be some frequently used debug code,or just some work in progress you need to move to another branch without committing. If the code is just WIP for the current branch we recommend using an interim commit instead.

The stash is a temporary store that holds a stack of uncommitted changes at a repository level. Commands given below work by default with the stash at the top of the stack, or you can optionally provide the stack reference.

To store your current changes at the top of the stash stack:

git stash <optional comment>

For example:

git stash "My debug code"

To see all your stashed items in the stash stack:

git stash list

This will show something like:

stash@{0}: WIP on master: 6ebd0e2... My debug code
stash@{1}: WIP on master: 9cc0589... My stashed changes

To see the details of an individual stash:

git stash show <optional stash ref>

To see the stash at the top of the stack:

git stash show

To see the second item from top:

git stash show stash@{1}

To restore a stash while keeping a copy in the stack:

git stash apply <optional stash ref>

To restore a stash and remove it from the stack:

git stash pop <optional stash ref>

To remove a single stash from the stack without applying it:

git stash drop <optional stash ref>

To clear out your entire stash stack:

git stash clear

For more details see:

http://www.kernel.org/pub/software/scm/git/docs/git-stash.html
http://book.git-scm.com/4_stashing.html

Getting Started/Build/KDE Support

2011-08-11T22:49:58Z

Odysseus: /* Qt Zeitgeist */

{{warning|This page is yet to be reviewed for changes required by the migration to Git. Information and commands on this page may no longer be valid and should be used with care. Please see the [[Development/Git|KDE Git hub page]] for more details. }}

{{Template:I18n/Language Navigation Bar|Getting_Started/Build/KDE_Support}}

{{TutorialBrowser|
series=Getting Started|
name=Building KDE4 From Source/KDE Support|
pre=[[../Qt|Qt]]|
next=[[../KDE_Development_Platform|KDE Development Platform]]|
|
}}

== Introduction ==

The KDE Support module contains a number of KDE developed and supported packages that the main KDE Modules depend upon. Your distribution packages may be sufficient for these requirements when building a KDE stable branch, but Unstable may sometimes require the latest versions to be built from source.

Most KDE Support packages have now migrated to Git as separate modules and must be built individually, although some are still left in Subversion and can be built as a single unit. The modules are listed below in a rough dependency order.

=== Required Steps ===

You need to have completed the following steps:
* Set up your [[../Environment|Build Environment]]
* Selected your [[../Recipes|Build Recipes]]
* Installed the [[../Requirements|System Requirements]]
* Installed or Built [[../Qt|Qt and related requirements]]
* Understand the [[../Requirements#Definitions|Requirements Table format]]

== Requirements ==

The following table summarizes all the Projects contained in KDE Support and the versions required for building KDE Software. The optional/mandatory coloring is based on the requirements of the KDE Development Platform, the requirements for building other KDE Modules or Applications may vary.

{| border="1" cellpadding="5" cellspacing="0"
|+ '''Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http://projects.kde.org/projects/kdesupport/automoc Automoc]
|
|
| No
|
|-
| [http://projects.kde.org/projects/kdesupport/attica Attica]
|
|
| Yes
|
|-
| [http://projects.kde.org/projects/kdesupport/polkit-qt-1 Polkit Qt]
|
|
| Yes
|
|-
| [https://projects.kde.org/projects/kdesupport/strigi Strigi]
|
|
| Yes
|
|-
| [http://projects.kde.org/projects/kdesupport/soprano Soprano]
|
|
| Yes
|
|-
| [http://projects.kde.org/projects/kdesupport/akonadi Akonadi]
|
|
| Yes
|
|-
| [http://projects.kde.org/projects/kdesupport/cagibi Cagibi]
|
|
| Yes
|
|-
| [https://projects.kde.org/projects/kdesupport/phonon Phonon]
|
|
| Yes
|
|-
| [http://projects.kde.org/projects/kdesupport/prison Prison]
|
| style="background-color:#66FF66" | Any
| Yes
| A Qt based barcode library
|-
| Oxygen Icons
|
|
| No
|
|-
| QImageBlitz
|
|
| Yes
|
|-
| TagLib
|
|
| Yes
|
|-
| cpp2xml
|
|
| No
|
|}

== Template ==

Project is a

{| border="1" cellpadding="5" cellspacing="0"
|-
| width="25%" style="background-color:#EFEFEF;" | '''Project Page'''
| width="75%" | [http://projects.kde.org/projects/kdesupport/project http://projects.kde.org/projects/kdesupport/project]
|-
| style="background-color:#EFEFEF;" | '''Stable Version'''
|
|-
| style="background-color:#EFEFEF;" | '''Required By'''
|
|-
| style="background-color:#EFEFEF;" | '''Easy Repository'''
| git clone kde:project.git
|-
| style="background-color:#EFEFEF;" | '''Full Repository'''
| git clone git://anongit.kde.org/project.git
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''KDE Software Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http://projects.kde.org/projects/kdesupport/project Project]
| style="background-color:#66FF66;" |
| style="background-color:#66FF66;" |
| Yes
| A library
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''Project Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http:// Project]
| style="background-color:#FF6666" |
| style="background-color:#FF6666" |
| Yes
| A library for
|}

== Automoc ==

Automoc is a tool to automate Qt moc file creation. Automoc '''MUST''' be built first as other KDE Support Modules depend on it.

{| border="1" cellpadding="5" cellspacing="0"
|-
| width="25%" style="background-color:#EFEFEF;" | '''Project Page'''
| width="75%" | [http://projects.kde.org/projects/kdesupport/automoc http://projects.kde.org/projects/kdesupport/automoc]
|-
| style="background-color:#EFEFEF;" | '''Stable Version'''
| 0.9.88
|-
| style="background-color:#EFEFEF;" | '''Required By'''
| All KDE Modules and Projects using moc
|-
| style="background-color:#EFEFEF;" | '''Easy Repository'''
| git clone kde:automoc.git
|-
| style="background-color:#EFEFEF;" | '''Full Repository'''
| git clone git://anongit.kde.org/automoc.git
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''KDE Software Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http://projects.kde.org/projects/kdesupport/automoc Automoc]
| style="background-color:#FF6666;" |
| style="background-color:#FF6666;" |
| No
| A tool to automate Qt moc file creation.
|}

== Attica ==

Attica is a library for accessing the Open Collaboration Services.

{| border="1" cellpadding="5" cellspacing="0"
|-
| width="25%" style="background-color:#EFEFEF;" | '''Project Page'''
| width="75%" | [http://projects.kde.org/projects/kdesupport/attica http://projects.kde.org/projects/kdesupport/attica]
|-
| style="background-color:#EFEFEF;" | '''Stable Version'''
| 0.2.0
|-
| style="background-color:#EFEFEF;" | '''Required By'''
|
|-
| style="background-color:#EFEFEF;" | '''Easy Repository'''
| git clone kde:attica.git
|-
| style="background-color:#EFEFEF;" | '''Full Repository'''
| git clone git://anongit.kde.org/attica.git
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''KDE Software Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http://projects.kde.org/projects/kdesupport/attica Attica]
| style="background-color:#66FF66;" |
| style="background-color:#66FF66;" |
| Yes
| A library for accessing the Open Collaboration Services.
|}

== Polkit Qt==

Polkit Qt is a library for accessing the PolicyKit authorization framework.

{| border="1" cellpadding="5" cellspacing="0"
|-
| width="25%" style="background-color:#EFEFEF;" | '''Project Page'''
| width="75%" | [http://projects.kde.org/projects/kdesupport/polkit-qt-1 http://projects.kde.org/projects/kdesupport/polkit-qt-1]
|-
| style="background-color:#EFEFEF;" | '''Stable Version'''
| 0.99
|-
| style="background-color:#EFEFEF;" | '''Required By'''
|
|-
| style="background-color:#EFEFEF;" | '''Easy Repository'''
| git clone kde:polkit-qt-1.git
|-
| style="background-color:#EFEFEF;" | '''Full Repository'''
| git clone git://anongit.kde.org/polkit-qt-1.git
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''KDE Software Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http://projects.kde.org/projects/kdesupport/polkit-qt-1 PolKit Qt]
| style="background-color:#66FF66;" |
| style="background-color:#66FF66;" |
| Yes
| A library for accessing the PolicyKit authorization framework.
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''Polkit Qt Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http://www.freedesktop.org/wiki/Software/PolicyKit PolicyKit]
| style="background-color:#FF6666" | >= 0.98
| style="background-color:#FF6666" | >= 0.98
| Yes
| The PolicyKit authorization framework. PolicyKit 0.98 is recommended, but Polkit Qt will build with any version.
|}

== Strigi ==

Strigi is a library for indexing files. Note that Strigi has now been split into a number of separate Git sub-projects, but these can still be cloned and built as a single entity using the Strigi parent project.

{| border="1" cellpadding="5" cellspacing="0"
|-
| width="25%" style="background-color:#EFEFEF;" | '''Project Page'''
| width="75%" | [http://projects.kde.org/projects/kdesupport/strigi http://projects.kde.org/projects/kdesupport/strigi]
|-
| style="background-color:#EFEFEF;" | '''Stable Version'''
| 0.7.2
|-
| style="background-color:#EFEFEF;" | '''Required By'''
|
|-
| style="background-color:#EFEFEF;" | '''Easy Repository'''
| git clone kde:strigi
|-
| style="background-color:#EFEFEF;" | '''Full Repository'''
| git clone git://anongit.kde.org/strigi
|}

{{ warning|As of 2011-03-21: After cloning the Strigi parent project, you will have to run the ''change_to_development_git.sh'' script to pull in all sub projects.}}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''KDE Software Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http://projects.kde.org/projects/kdesupport/strigi Strigi]
| style="background-color:#66FF66;" |
| style="background-color:#66FF66;" |
| Yes
| A library for indexing files.
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''Project Build Requirements'''
|-
! width="20%" style="background-color:#EFEFEF;" | Requirement
! width="15%" style="background-color:#EFEFEF;" | Stable Requires
! width="15%" style="background-color:#EFEFEF;" | Unstable Requires
! width="10%" style="background-color:#EFEFEF;" | Devel Pkgs?
! width="40%" style="background-color:#EFEFEF;" | Details
|-
| [http://qt.nokia.com/ Qt]
| style="background-color:#FF6666" | >= 4.3.0
| style="background-color:#FF6666" | >= 4.3.0
| Yes
| The Qt development framework.
|-
| [http://www.zlib.net/ libz]
| style="background-color:#FF6666" |
| style="background-color:#FF6666" |
| Yes
| A library for zip file compression
|-
| [http://bzip.org/ libbz2]
| style="background-color:#FF6666" |
| style="background-color:#FF6666" |
| Yes
| A library for bzip2 file compression.
|-
| [http://xmlsoft.org/ libxml2]
| style="background-color:#FF6666" |
| style="background-color:#FF6666" |
| Yes
| A library for parsing XML
|-
| [http://clucene.sourceforge.net/ Clucene]
| style="background-color:#66FF66" | >=0.9.16a
| style="background-color:#66FF66" | >=0.9.16a
| Yes
| A high-performance indexing and searching API. Version 0.9.17 does '''not''' work.
|-
| [http://www.exiv2.org/ Exiv2]
| style="background-color:#66FF66" |
| style="background-color:#66FF66" |
| Yes
| A library to manage image metadata.
|-
| [http://www.ffmpeg.org/ FFMPEG]
| style="background-color:#66FF66" |
| style="background-color:#66FF66" |
| Yes
| A library for reading audio and video files.
|-
| [http://www.freedesktop.org/wiki/Software/dbus DBus]
| style="background-color:#66FF66" |
| style="background-color:#66FF66" |
| Yes
| A message bus system.
|-
| [http://oss.sgi.com/projects/fam/ FAM]
| style="background-color:#66FF66" |
| style="background-color:#66FF66" |
| Yes
| A tool for file system monitoring.
|-
| [http://logging.apache.org/log4cxx/index.html Log4cxx]
| style="background-color:#66FF66" |
| style="background-color:#66FF66" |
| Yes
| A logging framework for C++
|-
| [http://sourceforge.net/projects/cppunit/ CppUnit]
| style="background-color:#66FF66" |
| style="background-color:#66FF66" |
| Yes
| A C++ Unit Testing framework
|}

== Soprano ==

Soprano is a library for storing RDF data for the Nepomuk semantic desktop.

Please see the [http://projects.kde.org/projects/kdesupport/soprano Soprano project page] for details.

Soprano must be built '''BEFORE''' Akonadi.

Easy: git clone kde:soprano.git
Full: git clone git://anongit.kde.org/soprano.git

== Akonadi ==

Akonadi is a library for caching PIM data.

Please see the [http://projects.kde.org/projects/kdesupport/akonadi Akonadi project page] for details.

Akonadi must be built '''AFTER''' Soprano.

Easy: git clone kde:akonadi.git
Full: git clone git://anongit.kde.org/akonadi.git

== Cagibi ==

Cagibi is a cache/proxy daemon for SSDP, the discovery part of UPnP.

Please see the [http://projects.kde.org/projects/kdesupport/cagibi Cagibi project page] for details.

Easy: git clone kde:cagibi.git
Full: git clone git://anongit.kde.org/cagibi.git

== Qt Zeitgeist ==

Qt Zeitgeist is a QT wrapper for the Zeitgeist logging program.

Please see the [http://projects.kde.org/projects/kdesupport/libqtzeitgeist Qt Zeitgeist project page] for details.

Easy: git clone kde:libqtzeitgeist.git
Full: git clone git://anongit.kde.org/libqtzeitgeist.git

== Phonon ==

Phonon is a sound system abstraction layer. This is usually packaged with Qt, but the Phonon version from Qt is not recent enough for KDE sound to work so you will need to build the required version yourself.

Please see the [https://projects.kde.org/projects/kdesupport/phonon Phonon project page] for details.

You need to install this Phonon in the same location as Phonon from Qt i.e. in $QTDIR and '''NOT''' in $KDEDIR.

=== Easy Recipe ===

This recipe assumes you have set up the recommended KDE scripts, environment variables, and git configuration.

cd <your source root directory>
git clone kde:phonon.git
cd phonon
cb
cmake <path to your module source dir>
\ -DCMAKE_INSTALL_PREFIX=$QTDIR
\ -DCMAKE_BUILD_TYPE=debugfull
\ -DKDE4_BUILD_TESTS=TRUE
make
make install

Note that make install may require root access.

=== Full Recipe ===

This recipe assumes you are not using the recommended scripts and have properly set up your own environment.

cd <your source root directory>
git clone git://anongit.kde.org/phonon.git
cd <your build root directory, or the module source dir>
mkdir <your module build dir>
cd <your module build dir>
cmake <path to your module source dir>
\ -DCMAKE_INSTALL_PREFIX=$QTDIR
\ -DCMAKE_BUILD_TYPE=debugfull
\ -DKDE4_BUILD_TESTS=TRUE
make
make install

=== Backend ===

Building the main Phonon module is sufficient for building KDE. If you also want to play sound then you need to build a backend. Choose a suitable backend from those available below:

git clone git://anongit.kde.org/phonon-gstreamer.git
git clone git://anongit.kde.org/phonon-xine.git
git clone git://anongit.kde.org/phonon-directshow.git
git clone git://anongit.kde.org/phonon-mmf.git
git clone git://anongit.kde.org/phonon-quicktime.git
git clone git://anongit.kde.org/phonon-waveout.git

Note that DirectShow is for Windows only.

=== Troubleshooting ===

If you get an error like

designer: symbol lookup error: /path/to/kde/lib/kde4/plugins/phonon_backend/phonon_xine.so:
undefined symbol: _ZN6Phonon12PulseSupport11getInstanceEv

while running Qt Designer you need to:

rm $QTDIR/lib/libphonon.so.4

== Prison ==

Prison is a barcode library to enable optional barcode support in KDE Software. It was introduced in the KDE 4.7 Release Cycle.

{| border="1" cellpadding="5" cellspacing="0"
|-
| width="25%" | '''Project Page'''
| width="75%" | [http://projects.kde.org/projects/kdesupport/prison http://projects.kde.org/projects/kdesupport/prison]
|-
| '''Stable Version'''
| Unreleased
|-
| '''Required By'''
| No KDE Modules as yet
|-
| '''Easy Repository'''
| git clone kde:prison.git
|-
| '''Full Repository'''
| git clone git://anongit.kde.org/prison.git
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''KDE Software Build Requirements'''
|-
! width="20%" | Requirement
! width="15%" | Stable Requires
! width="15%" | Unstable Requires
! width="10%" | Devel Pkgs?
! width="40%" | Details
|-
| [http://projects.kde.org/projects/kdesupport/prison Prison]
|
| style="background-color:#6ECFFF;" | Any
| Yes
| A Qt based barcode library
|}

{| border="1" cellpadding="5" cellspacing="0"
|+ '''Prison Build Requirements'''
|-
! width="20%" | Requirement
! width="15%" | Stable Requires
! width="15%" | Unstable Requires
! width="10%" | Devel Pkgs?
! width="40%" | Details
|-
| [http://fukuchi.org/works/qrencode/index.en.html QRencode]
|
| style="background-color:#FF6E6E;" | Any
| Yes
| A library for reading and writing QR Code barcodes
|-
| [http://www.libdmtx.org/ Dmtx]
|
| style="background-color:#FF6E6E;" | Any
| Yes
| A library for reading and writing Data Matrix 2D barcodes
|}

== kdesupport svn module ==

A number of kdesupport packages are still in svn:

* oxygen-icons
* qimageblitz - for building kde-workspace
* taglib
* taglib-extras
* cpp2xml
* twine - for building kdebindings
* emerge - for building kde on windows

These packages can be checked out and built together with a single recipe.

Note that QCA lives in kdesupport svn but is not built by default. It is recommended that you use your system QCA packages and only checkout the kdesupport svn version if you are going to develop QCA.

=== Easy Recipe ===

This recipe assumes you have set up the recommended KDE scripts, environment variables, and git configuration.

cd <your source root directory>
svn checkout svn://anonsvn.kde.org/home/kde/trunk/kdesupport/
cd kdesupport
kdebuild

=== Full Recipe ===

This recipe assumes you are not using the recommended scripts and have properly set up your own environment.

cd <your source root directory>
svn checkout svn://anonsvn.kde.org/home/kde/trunk/kdesupport/
cd <your build root directory, or the module source dir>
mkdir <your module build dir>
cd <your module build dir>
cmake <path to your module source dir>
\ -DCMAKE_INSTALL_PREFIX=$KDEDIR
\ -DCMAKE_BUILD_TYPE=debugfull
\ -DKDE4_BUILD_TESTS=TRUE
make
make install

== Troubleshooting ==

If you get a message related to
target libQtTest.so not found
you may need to recompile qt-kde. This time you should take out
-nomake demos -nomake examples
from the configure command, so that Qt generates library QtTest.

If you get
CMake Error: Qt qmake not found!
Then:
1) uncomment Qt section in .bashrc script (QTDIR, QT_PLUGINS_DIR,
PKG_CONFIG_PATH variable settings).
2) source ~/.bashrc
3) cd && cd qt-kde
4) make confclean
5) repeat steps for installing Qt (from ./configure line).
6) retry building kdesupport

= Next Step =

Once all the KDE Support requirements have been installed it is time to install the [[../KDE_Development_Platform|KDE Development Platform]]

Development/Git/Feature Branch Workflow

2011-06-13T17:26:40Z

Odysseus: /* Remote Feature Development */

THIS IS A DRAFT, DO NOT USE!

= Feature Branch Workflow =

This Git Workflow is the recommended KDE Git Workflow for smaller projects where new features are developed in local and/or remote feature branches before being reviewed and merged back into the master branch.

This workflow is designed to be used after initial use of the [[Development/Git/Simple_Workflow|Simple Workflow]]. It is assumed you have read and mastered the basic concepts as outlined in that Workflow, such as unstaged and staged changes, committing, rebasing and pushing.

Note that each module may choose to adopt a more complex workflow, in particular the Integration Branch Workflow, and you should check with your modules maintainers if this is the case.

More detailed information can be found on the main [[Development/Git|KDE Git page]]. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

See the [[Development/Git/Simple_Workflow#Set-up|Simple Workflow Set-up]] section for instructions on configuring Git and Cloning your Repository

== Local Feature Development ==

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

=== Create a Local Work Branch ===

To see what local branches you have:

git branch

This will initially appear as follows, with the * indicating your current working branch:

* master

To see all local and remote branches:

git branch -a

This will initially look something like:

* master
remotes/origin/HEAD -> origin/master
remotes/origin/KDE/4.5
remotes/origin/KDE/4.6
remotes/origin/kdecore/klocale-win
remotes/origin/kdeui/kdatetimeedit

To create a new local branch:

git branch <new-branch>

Now running <tt>git branch</tt> will show:

* master
my-new-branch

To change to the new branch to work on it:

git checkout <new-branch>

Now running <tt>git branch</tt> will show:

master
* my-new-branch

This sequence will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' a remote branch and is recommended for most work branches:

git branch --track <local-branch> <remote-branch>

For example to develop a new feature called 'bar' based on the central repository master branch:

git branch --track new-bar-feature origin/master

=== Making Changes ===

You can now make [[Development/Git/Simple_Workflow#Making_Local_Changes_and_Commits|local changes and commits]], and [[Development/Git/Simple_Workflow#Pushing_Your_Changes_To_The_Central_Repository|push them to the central repository]] exactly as described in the [[Development/Git/Simple_Workflow|Simple Workflow]].

Your project may require changes to be reviewed before pushing to the central code repository. All projects on git.kde.org automatically have a [[Development/Review_Board|Review Board]] group created for them which you can use for this purpose. It is recommended that you use the [[Development/Review_Board#Using_post-review_to_post_changes_for_review|post-review script]] to automatically generate and upload the diff of your changes.

=== Deleting Local Branches ===

Once you have finished with a local feature branch and pushed all your commits to the central repository you can delete the local branch if you no longer require it.

First, you have to change to a different branch:

git checkout master

Then you can delete the feature branch:

git -d <local-branch>

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository. This workflow is recommended for larger features or where there are many developers on a project.

The main disadvantage of local feature branch development is no-one else can see your code changes or help you until the finished feature is pushed to master on the central repository. You could resolve this by regularly pushing incomplete features to master, but this will lead to master becoming more unstable. The proper solution is to create a Remote Feature Branch on the central repository where you can push your interim work for others to see and also push changes to.

TODO: Finish this.

TODO Steps:
* Create the remote branch tracking master
git push origin master:refs/heads/<remote-branch>
git fetch origin
* Create your local branch tracking the remote branch
git branch --track <local-branch> origin/<remote-branch>
git checkout <local-branch>
* Do local dev and commits, rebase, push
* When to use Merges, when to Rebase?
* Once local commits are pushed you cannot rewrite them!

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and possibly a special naming scheme to distinguish them. For example, kdelibs includes the following branches on the central repository:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs.

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

In the [[Development/Git/Simple_Workflow#Local_Bug_Fixing|Simple Workflow bug fixing]] section we describe a simple way to perform bug fixes for both stable and unstable branches in the same repository clone.

The basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

One alternative is to have two separate clones using two separate build environments, but this wastes disk space and causes problems with keeping the separate clones in sync.

A better alternative is to use the [[Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for the stable and unstable branches using the same repository clone. This depends on you setting different up KDE Environments for the separate builds.

TODO: Finish this.

Development/Git/Feature Branch Workflow

2011-06-13T09:49:11Z

Odysseus: /* Remote Feature Development */

THIS IS A DRAFT, DO NOT USE!

= Feature Branch Workflow =

This Git Workflow is the recommended KDE Git Workflow for smaller projects where new features are developed in local and/or remote feature branches before being reviewed and merged back into the master branch.

This workflow is designed to be used after initial use of the [[Development/Git/Simple_Workflow|Simple Workflow]]. It is assumed you have read and mastered the basic concepts as outlined in that Workflow, such as unstaged and staged changes, committing, rebasing and pushing.

Note that each module may choose to adopt a more complex workflow, in particular the Integration Branch Workflow, and you should check with your modules maintainers if this is the case.

More detailed information can be found on the main [[Development/Git|KDE Git page]]. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

See the [[Development/Git/Simple_Workflow#Set-up|Simple Workflow Set-up]] section for instructions on configuring Git and Cloning your Repository

== Local Feature Development ==

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

=== Create a Local Work Branch ===

To see what local branches you have:

git branch

This will initially appear as follows, with the * indicating your current working branch:

* master

To see all local and remote branches:

git branch -a

This will initially look something like:

* master
remotes/origin/HEAD -> origin/master
remotes/origin/KDE/4.5
remotes/origin/KDE/4.6
remotes/origin/kdecore/klocale-win
remotes/origin/kdeui/kdatetimeedit

To create a new local branch:

git branch <new-branch>

Now running <tt>git branch</tt> will show:

* master
my-new-branch

To change to the new branch to work on it:

git checkout <new-branch>

Now running <tt>git branch</tt> will show:

master
* my-new-branch

This sequence will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' a remote branch and is recommended for most work branches:

git branch --track <local-branch> <remote-branch>

For example to develop a new feature called 'bar' based on the central repository master branch:

git branch --track new-bar-feature origin/master

=== Making Changes ===

You can now make [[Development/Git/Simple_Workflow#Making_Local_Changes_and_Commits|local changes and commits]], and [[Development/Git/Simple_Workflow#Pushing_Your_Changes_To_The_Central_Repository|push them to the central repository]] exactly as described in the [[Development/Git/Simple_Workflow|Simple Workflow]].

Your project may require changes to be reviewed before pushing to the central code repository. All projects on git.kde.org automatically have a [[Development/Review_Board|Review Board]] group created for them which you can use for this purpose. It is recommended that you use the [[Development/Review_Board#Using_post-review_to_post_changes_for_review|post-review script]] to automatically generate and upload the diff of your changes.

=== Deleting Local Branches ===

Once you have finished with a local feature branch and pushed all your commits to the central repository you can delete the local branch if you no longer require it.

First, you have to change to a different branch:

git checkout master

Then you can delete the feature branch:

git -d <local-branch>

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository. This workflow is recommended for larger features or where there are many developers on a project.

The main disadvantage of local feature branch development is no-one else can see your code changes or help you until the finished feature is pushed to master on the central repository. You could resolve this by regularly pushing incomplete features to master, but this will lead to master becoming more unstable. The proper solution is to create a Remote Feature Branch on the central repository where you can push your interim work for others to see and also push changes to.

TODO: Finish this.

TODO Steps:
* Create the remote branch tracking master
* Create your local branch tracking the remote branch
* Do local dev and commits, rebase, push
* When to use Merges, when to Rebase?
* Once local commits are pushed you cannot rewrite them!

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and possibly a special naming scheme to distinguish them. For example, kdelibs includes the following branches on the central repository:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs.

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

In the [[Development/Git/Simple_Workflow#Local_Bug_Fixing|Simple Workflow bug fixing]] section we describe a simple way to perform bug fixes for both stable and unstable branches in the same repository clone.

The basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

One alternative is to have two separate clones using two separate build environments, but this wastes disk space and causes problems with keeping the separate clones in sync.

A better alternative is to use the [[Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for the stable and unstable branches using the same repository clone. This depends on you setting different up KDE Environments for the separate builds.

TODO: Finish this.

Development/Git/Feature Branch Workflow

2011-06-13T09:40:36Z

Odysseus: /* Local Bug Fixing */

THIS IS A DRAFT, DO NOT USE!

= Feature Branch Workflow =

This Git Workflow is the recommended KDE Git Workflow for smaller projects where new features are developed in local and/or remote feature branches before being reviewed and merged back into the master branch.

This workflow is designed to be used after initial use of the [[Development/Git/Simple_Workflow|Simple Workflow]]. It is assumed you have read and mastered the basic concepts as outlined in that Workflow, such as unstaged and staged changes, committing, rebasing and pushing.

Note that each module may choose to adopt a more complex workflow, in particular the Integration Branch Workflow, and you should check with your modules maintainers if this is the case.

More detailed information can be found on the main [[Development/Git|KDE Git page]]. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

See the [[Development/Git/Simple_Workflow#Set-up|Simple Workflow Set-up]] section for instructions on configuring Git and Cloning your Repository

== Local Feature Development ==

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

=== Create a Local Work Branch ===

To see what local branches you have:

git branch

This will initially appear as follows, with the * indicating your current working branch:

* master

To see all local and remote branches:

git branch -a

This will initially look something like:

* master
remotes/origin/HEAD -> origin/master
remotes/origin/KDE/4.5
remotes/origin/KDE/4.6
remotes/origin/kdecore/klocale-win
remotes/origin/kdeui/kdatetimeedit

To create a new local branch:

git branch <new-branch>

Now running <tt>git branch</tt> will show:

* master
my-new-branch

To change to the new branch to work on it:

git checkout <new-branch>

Now running <tt>git branch</tt> will show:

master
* my-new-branch

This sequence will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' a remote branch and is recommended for most work branches:

git branch --track <local-branch> <remote-branch>

For example to develop a new feature called 'bar' based on the central repository master branch:

git branch --track new-bar-feature origin/master

=== Making Changes ===

You can now make [[Development/Git/Simple_Workflow#Making_Local_Changes_and_Commits|local changes and commits]], and [[Development/Git/Simple_Workflow#Pushing_Your_Changes_To_The_Central_Repository|push them to the central repository]] exactly as described in the [[Development/Git/Simple_Workflow|Simple Workflow]].

Your project may require changes to be reviewed before pushing to the central code repository. All projects on git.kde.org automatically have a [[Development/Review_Board|Review Board]] group created for them which you can use for this purpose. It is recommended that you use the [[Development/Review_Board#Using_post-review_to_post_changes_for_review|post-review script]] to automatically generate and upload the diff of your changes.

=== Deleting Local Branches ===

Once you have finished with a local feature branch and pushed all your commits to the central repository you can delete the local branch if you no longer require it.

First, you have to change to a different branch:

git checkout master

Then you can delete the feature branch:

git -d <local-branch>

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository. This workflow is recommended for larger features or where there are many developers on a project.

The main disadvantage of local feature branch development is no-one else can see your code changes or help you until the finished feature is pushed to master on the central repository. You could resolve this by regularly pushing incomplete features to master, but this will lead to master becoming more unstable. The proper solution is to create a Remote Feature Branch on the central repository where you can push your interim work for others to see and also push changes.

TODO: Finish this.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and possibly a special naming scheme to distinguish them. For example, kdelibs includes the following branches on the central repository:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs.

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

In the [[Development/Git/Simple_Workflow#Local_Bug_Fixing|Simple Workflow bug fixing]] section we describe a simple way to perform bug fixes for both stable and unstable branches in the same repository clone.

The basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

One alternative is to have two separate clones using two separate build environments, but this wastes disk space and causes problems with keeping the separate clones in sync.

A better alternative is to use the [[Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for the stable and unstable branches using the same repository clone. This depends on you setting different up KDE Environments for the separate builds.

TODO: Finish this.

Development/Git/Feature Branch Workflow

2011-06-13T09:40:12Z

Odysseus: /* Remote Feature Development */

THIS IS A DRAFT, DO NOT USE!

= Feature Branch Workflow =

This Git Workflow is the recommended KDE Git Workflow for smaller projects where new features are developed in local and/or remote feature branches before being reviewed and merged back into the master branch.

This workflow is designed to be used after initial use of the [[Development/Git/Simple_Workflow|Simple Workflow]]. It is assumed you have read and mastered the basic concepts as outlined in that Workflow, such as unstaged and staged changes, committing, rebasing and pushing.

Note that each module may choose to adopt a more complex workflow, in particular the Integration Branch Workflow, and you should check with your modules maintainers if this is the case.

More detailed information can be found on the main [[Development/Git|KDE Git page]]. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

See the [[Development/Git/Simple_Workflow#Set-up|Simple Workflow Set-up]] section for instructions on configuring Git and Cloning your Repository

== Local Feature Development ==

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

=== Create a Local Work Branch ===

To see what local branches you have:

git branch

This will initially appear as follows, with the * indicating your current working branch:

* master

To see all local and remote branches:

git branch -a

This will initially look something like:

* master
remotes/origin/HEAD -> origin/master
remotes/origin/KDE/4.5
remotes/origin/KDE/4.6
remotes/origin/kdecore/klocale-win
remotes/origin/kdeui/kdatetimeedit

To create a new local branch:

git branch <new-branch>

Now running <tt>git branch</tt> will show:

* master
my-new-branch

To change to the new branch to work on it:

git checkout <new-branch>

Now running <tt>git branch</tt> will show:

master
* my-new-branch

This sequence will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' a remote branch and is recommended for most work branches:

git branch --track <local-branch> <remote-branch>

For example to develop a new feature called 'bar' based on the central repository master branch:

git branch --track new-bar-feature origin/master

=== Making Changes ===

You can now make [[Development/Git/Simple_Workflow#Making_Local_Changes_and_Commits|local changes and commits]], and [[Development/Git/Simple_Workflow#Pushing_Your_Changes_To_The_Central_Repository|push them to the central repository]] exactly as described in the [[Development/Git/Simple_Workflow|Simple Workflow]].

Your project may require changes to be reviewed before pushing to the central code repository. All projects on git.kde.org automatically have a [[Development/Review_Board|Review Board]] group created for them which you can use for this purpose. It is recommended that you use the [[Development/Review_Board#Using_post-review_to_post_changes_for_review|post-review script]] to automatically generate and upload the diff of your changes.

=== Deleting Local Branches ===

Once you have finished with a local feature branch and pushed all your commits to the central repository you can delete the local branch if you no longer require it.

First, you have to change to a different branch:

git checkout master

Then you can delete the feature branch:

git -d <local-branch>

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository. This workflow is recommended for larger features or where there are many developers on a project.

The main disadvantage of local feature branch development is no-one else can see your code changes or help you until the finished feature is pushed to master on the central repository. You could resolve this by regularly pushing incomplete features to master, but this will lead to master becoming more unstable. The proper solution is to create a Remote Feature Branch on the central repository where you can push your interim work for others to see and also push changes.

TODO: Finish this.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, kdelibs includes the following branches on the central repository:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs.

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

In the [[Development/Git/Simple_Workflow#Local_Bug_Fixing|Simple Workflow bug fixing]] section we describe a simple way to perform bug fixes for both stable and unstable branches in the same repository clone.

The basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

One alternative is to have two separate clones using two separate build environments, but this wastes disk space and causes problems with keeping the separate clones in sync.

A better alternative is to use the [[Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for the stable and unstable branches using the same repository clone. This depends on you setting different up KDE Environments for the separate builds.

TODO: Finish this.

Development/Git/Simple Workflow

2011-06-13T09:34:56Z

Odysseus: /* Local Bug Fixing */

DANGER WILL ROBINSON!!! THIS IS AN INCOMPLETE DRAFT!!!

= Simple Workflow =

This workflow is designed to be as close as possible to the KDE SVN Workflow. It is only recommended to be used for the first week or two of using Git with KDE while you become familiar with the basic Git commands. Once comfortable with the basic commands you should then move on to the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

In particular this workflow will not use git branches, merging or any remote features, all feature development work will be in the local master branch (the Git name for trunk).

More detailed information can be found on the main [[Development/Git|KDE Git page]], in particular the [[Development/Git#Git_for_SVN_Users|Git for Subversion Users]] section. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow all the instructions on the [[Development/Git/Configuration|KDE Git Configuration]] page, the instructions given below assume you are using the standard configuration.

=== Clone your repository ===

You need to copy your central code repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>
cd <project>

For example to clone kdelibs:

git clone kde:kdelibs
cd kdelibs

See the [[Getting_Started/Build/Environment#Source_Path|KDE Build Environment]] page for advice on structuring your source directory.

If you have a slow or intermittent internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the [https://projects.kde.org/projects projects.kde.org] Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Local Feature Development ==

This section documents the basic workflow for developing a new feature for the master unstable branch (aka trunk in subversion). You will first make local code changes and commit them in your local repository before pushing them to the central code repository.

=== Making Local Changes and Commits ===

Changing and building code itself is no different from when using subversion, but how changed files are managed and committed is very different, as are the names and commands used. There are two key differences:
* Locally modified files can have different states that determine whether they get committed or not.
* Committing code is only local, it does not push your changes to the central repository which requires an extra step.

Files in a git repository can be in various states:
* Untracked: Files in your local repository directory that Git is not tracking changes to and are not in the central repository.
* Tracked: Files that git tracks changes to.
* Unstaged: Tracked files that have had modifications to them but have not yet been staged or committed.
* Staged: Tracked files that have had modifications made to them and have been marked to be included in the next commit
* Committed: Files that git is tracking and that have been included in a local commit that may or may not be included in the central repository.

Note that different versions of a file can be in the Untracked and Tracked states at the same time.

This difference between staged and unstaged changes allows you to choose what changes you want in each commit.

To see what the current status of your local repository is:

git status

This will show you the status as follows;

# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: src/kstagedfile.h
#
# Changed but not updated:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: src/kchangedfile.h
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# src/kuntrackedfile.txt

To add a changed file to the staging area, or to add a new file to be tracked by the repository:

git add <filename>

To delete a file from the repository and add the deletion to the staging area:

git rm <filename>

To reset a staged file to be unstaged but without losing your changes:

git reset HEAD <filename>

To reset an unstaged file to the currently committed version and irretrievably throw away your changes:

git checkout <filename>

The git commit command differs from the svn commit command in only creating a commit in your local clone of the repository, it does not merge the changes into the central repository. This allows you to queue up a series of small changes before merging them into the central repository. This local commit history can [[Development/Git/Recipes#Interactive_Rebasing|also be modified]] before you finally do push the changes.

The git commit command adds all files in the staged state into a new commit:

git commit

If you have only changed tracked files then you can automatically add all tracked files that have been changed into staging and commit all the staged files in one command:

git commit -a

=== Seeing What You Changed ===

To see a list of what files have been changed but not yet committed:

git status

To see what code changes have been made but not yet staged:

git diff
git diff <filename>

To see what code changes have been staged but not committed:

git diff --staged
git diff --staged <filename>

To see all the commits made:

git log

To see what changes were made in a commit:

git show <sha5>

The Git diff, log and show commands have many options for changing what is shown. In particular diff can show the difference in a file between any two commits.

=== Pushing Your Changes To The Central Repository ===

When you are ready to push all your local commits to the central repository, you first need to update to the latest version of the master code in the central repository:

git pull --rebase

This will update the underlying master code and apply your commits on the top of the latest version of the central repository, this is known as a rebase. Normally the rebase should apply cleanly, but sometimes there will be a conflict which you will need to resolve before you can complete applying your commits. There will be instructions given by git on how to complete the commit if required [TODO: get a copy of the output text].

Note that you cannot rebase if you have uncommitted changes. If you need to rebase but have changes that you don't want to commit, then you will need to [[Development/Git/Recipes#Stashing_Changes|stash the changes]].

Depending on how much the underlying master code has changed you may want to rebuild and test the code after doing the rebase, before doing a final rebase. It is recommended to do regular rebase's between commits to keep the possibility of conflicts to a minimum.

Once your local commits have been cleanly reapplied you can push your changes to the central repository:

git push origin master:master

Git will report if the push was successful or explain why it failed.

== Local Bug Fixing ==

If your bug fix is only for unstable master then no special actions are required, just follow the same steps as the feature development workflow above.

If your bug fix is for a stable branch then this cannot be done without using git branches. The steps required will be given below but not explained in any detail. If possible it is recommended you wait until you are familiar with using the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

The steps detailed below are very inefficient as they use the same build tree and environment for unstable and stable which may cause a lot of rebuilding. A more efficient method is detailed in the [[Development/Git/Feature_Branch_Workflow#Local_Bug_Fixing|Feature Branch Workflow]].

First, find out the name of the stable branch you want to bug fix:

git branch -r

This will list all the branches on the central repository, for example kdelibs includes the following branches:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs which we will use for this example.

Next, create a local branch pointing to the stable release branch you want to bug fix:

git branch --track <local-branch> <remote-branch>
git checkout <local-branch>

For example, to create a local kdelibs 4.6 stable branch:

git branch --track KDE/4.6 origin/KDE/4.6
git checkout KDE/4.6

If you have previously created the stable branch and want to do a new bug fix, then simply check it out again and update it:

git checkout <local-branch>
git pull --rebase

Now make your required changes to the code, build and test. Once done commit the code changes to your local repository, remembering to include the BUG: and FIXED-IN: keywords in the commit message:

git commit -a

Make a note of the sha5 of the commit as you will need it later to copy the commit to the unstable master branch.

Now you can push your changes into the central code repository:

git pull --rebase
git push origin <local-branch>:<remote-branch>

For your kdelibs example this would be:

git pull --rebase
git push origin KDE/4.6:KDE/4.6

The next step is to apply the bug fix to the unstable master branch. First check the master branch back out and update it:

git checkout master
git pull --rebase

Next, Git makes it easy to apply the existing bug fix from the stable branch by using the cherry-pick command:

git cherry-pick -x -e <sha5 of stable commit>

This will allow you to edit the commit message as required before the change is committed. If the patch does not apply cleanly a message will appear and the changes will not be committed. You will then have to edit the changes and finish the commit manually.

Once cleanly applied and committed you can build and test the change, then push them to the central code repository:

git pull --rebase
git push origin master:master

Development/Git/Feature Branch Workflow

2011-06-13T09:29:01Z

Odysseus: /* Making Changes */

THIS IS A DRAFT, DO NOT USE!

= Feature Branch Workflow =

This Git Workflow is the recommended KDE Git Workflow for smaller projects where new features are developed in local and/or remote feature branches before being reviewed and merged back into the master branch.

This workflow is designed to be used after initial use of the [[Development/Git/Simple_Workflow|Simple Workflow]]. It is assumed you have read and mastered the basic concepts as outlined in that Workflow, such as unstaged and staged changes, committing, rebasing and pushing.

Note that each module may choose to adopt a more complex workflow, in particular the Integration Branch Workflow, and you should check with your modules maintainers if this is the case.

More detailed information can be found on the main [[Development/Git|KDE Git page]]. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

See the [[Development/Git/Simple_Workflow#Set-up|Simple Workflow Set-up]] section for instructions on configuring Git and Cloning your Repository

== Local Feature Development ==

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

=== Create a Local Work Branch ===

To see what local branches you have:

git branch

This will initially appear as follows, with the * indicating your current working branch:

* master

To see all local and remote branches:

git branch -a

This will initially look something like:

* master
remotes/origin/HEAD -> origin/master
remotes/origin/KDE/4.5
remotes/origin/KDE/4.6
remotes/origin/kdecore/klocale-win
remotes/origin/kdeui/kdatetimeedit

To create a new local branch:

git branch <new-branch>

Now running <tt>git branch</tt> will show:

* master
my-new-branch

To change to the new branch to work on it:

git checkout <new-branch>

Now running <tt>git branch</tt> will show:

master
* my-new-branch

This sequence will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' a remote branch and is recommended for most work branches:

git branch --track <local-branch> <remote-branch>

For example to develop a new feature called 'bar' based on the central repository master branch:

git branch --track new-bar-feature origin/master

=== Making Changes ===

You can now make [[Development/Git/Simple_Workflow#Making_Local_Changes_and_Commits|local changes and commits]], and [[Development/Git/Simple_Workflow#Pushing_Your_Changes_To_The_Central_Repository|push them to the central repository]] exactly as described in the [[Development/Git/Simple_Workflow|Simple Workflow]].

Your project may require changes to be reviewed before pushing to the central code repository. All projects on git.kde.org automatically have a [[Development/Review_Board|Review Board]] group created for them which you can use for this purpose. It is recommended that you use the [[Development/Review_Board#Using_post-review_to_post_changes_for_review|post-review script]] to automatically generate and upload the diff of your changes.

=== Deleting Local Branches ===

Once you have finished with a local feature branch and pushed all your commits to the central repository you can delete the local branch if you no longer require it.

First, you have to change to a different branch:

git checkout master

Then you can delete the feature branch:

git -d <local-branch>

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

The main disadvantage of local feature branch development is no-one else can see your code changes or help you until the finished feature is pushed to the central repository.

TODO: Finish this.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, kdelibs includes the following branches on the central repository:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs.

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

In the [[Development/Git/Simple_Workflow#Local_Bug_Fixing|Simple Workflow bug fixing]] section we describe a simple way to perform bug fixes for both stable and unstable branches in the same repository clone.

The basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

One alternative is to have two separate clones using two separate build environments, but this wastes disk space and causes problems with keeping the separate clones in sync.

A better alternative is to use the [[Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for the stable and unstable branches using the same repository clone. This depends on you setting different up KDE Environments for the separate builds.

TODO: Finish this.

Development/Git/Simple Workflow

2011-06-13T09:20:07Z

Odysseus: /* Local Bug Fixing */

DANGER WILL ROBINSON!!! THIS IS AN INCOMPLETE DRAFT!!!

= Simple Workflow =

This workflow is designed to be as close as possible to the KDE SVN Workflow. It is only recommended to be used for the first week or two of using Git with KDE while you become familiar with the basic Git commands. Once comfortable with the basic commands you should then move on to the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

In particular this workflow will not use git branches, merging or any remote features, all feature development work will be in the local master branch (the Git name for trunk).

More detailed information can be found on the main [[Development/Git|KDE Git page]], in particular the [[Development/Git#Git_for_SVN_Users|Git for Subversion Users]] section. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow all the instructions on the [[Development/Git/Configuration|KDE Git Configuration]] page, the instructions given below assume you are using the standard configuration.

=== Clone your repository ===

You need to copy your central code repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>
cd <project>

For example to clone kdelibs:

git clone kde:kdelibs
cd kdelibs

See the [[Getting_Started/Build/Environment#Source_Path|KDE Build Environment]] page for advice on structuring your source directory.

If you have a slow or intermittent internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the [https://projects.kde.org/projects projects.kde.org] Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Local Feature Development ==

This section documents the basic workflow for developing a new feature for the master unstable branch (aka trunk in subversion). You will first make local code changes and commit them in your local repository before pushing them to the central code repository.

=== Making Local Changes and Commits ===

Changing and building code itself is no different from when using subversion, but how changed files are managed and committed is very different, as are the names and commands used. There are two key differences:
* Locally modified files can have different states that determine whether they get committed or not.
* Committing code is only local, it does not push your changes to the central repository which requires an extra step.

Files in a git repository can be in various states:
* Untracked: Files in your local repository directory that Git is not tracking changes to and are not in the central repository.
* Tracked: Files that git tracks changes to.
* Unstaged: Tracked files that have had modifications to them but have not yet been staged or committed.
* Staged: Tracked files that have had modifications made to them and have been marked to be included in the next commit
* Committed: Files that git is tracking and that have been included in a local commit that may or may not be included in the central repository.

Note that different versions of a file can be in the Untracked and Tracked states at the same time.

This difference between staged and unstaged changes allows you to choose what changes you want in each commit.

To see what the current status of your local repository is:

git status

This will show you the status as follows;

# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: src/kstagedfile.h
#
# Changed but not updated:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: src/kchangedfile.h
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# src/kuntrackedfile.txt

To add a changed file to the staging area, or to add a new file to be tracked by the repository:

git add <filename>

To delete a file from the repository and add the deletion to the staging area:

git rm <filename>

To reset a staged file to be unstaged but without losing your changes:

git reset HEAD <filename>

To reset an unstaged file to the currently committed version and irretrievably throw away your changes:

git checkout <filename>

The git commit command differs from the svn commit command in only creating a commit in your local clone of the repository, it does not merge the changes into the central repository. This allows you to queue up a series of small changes before merging them into the central repository. This local commit history can [[Development/Git/Recipes#Interactive_Rebasing|also be modified]] before you finally do push the changes.

The git commit command adds all files in the staged state into a new commit:

git commit

If you have only changed tracked files then you can automatically add all tracked files that have been changed into staging and commit all the staged files in one command:

git commit -a

=== Seeing What You Changed ===

To see a list of what files have been changed but not yet committed:

git status

To see what code changes have been made but not yet staged:

git diff
git diff <filename>

To see what code changes have been staged but not committed:

git diff --staged
git diff --staged <filename>

To see all the commits made:

git log

To see what changes were made in a commit:

git show <sha5>

The Git diff, log and show commands have many options for changing what is shown. In particular diff can show the difference in a file between any two commits.

=== Pushing Your Changes To The Central Repository ===

When you are ready to push all your local commits to the central repository, you first need to update to the latest version of the master code in the central repository:

git pull --rebase

This will update the underlying master code and apply your commits on the top of the latest version of the central repository, this is known as a rebase. Normally the rebase should apply cleanly, but sometimes there will be a conflict which you will need to resolve before you can complete applying your commits. There will be instructions given by git on how to complete the commit if required [TODO: get a copy of the output text].

Note that you cannot rebase if you have uncommitted changes. If you need to rebase but have changes that you don't want to commit, then you will need to [[Development/Git/Recipes#Stashing_Changes|stash the changes]].

Depending on how much the underlying master code has changed you may want to rebuild and test the code after doing the rebase, before doing a final rebase. It is recommended to do regular rebase's between commits to keep the possibility of conflicts to a minimum.

Once your local commits have been cleanly reapplied you can push your changes to the central repository:

git push origin master:master

Git will report if the push was successful or explain why it failed.

== Local Bug Fixing ==

If your bug fix is only for unstable master then no special actions are required, just follow the same steps as the feature development workflow above.

If your bug fix is for a stable branch then this cannot be done without using git branches. The steps required will be given below but not explained in any detail. If possible it is recommended you wait until you are familiar with using the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

The steps detailed below are very inefficient as they use the same build tree and environment for unstable and stable which may cause a lot of rebuilding. A more efficient method is detailed in the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

First, find out the name of the stable branch you want to bug fix:

git branch -r

This will list all the branches on the central repository, for example kdelibs includes the following branches:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs which we will use for this example.

Next, create a local branch pointing to the stable release branch you want to bug fix:

git branch --track <local-branch> <remote-branch>
git checkout <local-branch>

For example, to create a local kdelibs 4.6 stable branch:

git branch --track KDE/4.6 origin/KDE/4.6
git checkout KDE/4.6

If you have previously created the stable branch and want to do a new bug fix, then simply check it out again and update it:

git checkout <local-branch>
git pull --rebase

Now make your required changes to the code, build and test. Once done commit the code changes to your local repository, remembering to include the BUG: and FIXED-IN: keywords in the commit message:

git commit -a

Make a note of the sha5 of the commit as you will need it later to copy the commit to the unstable master branch.

Now you can push your changes into the central code repository:

git pull --rebase
git push origin <local-branch>:<remote-branch>

For your kdelibs example this would be:

git pull --rebase
git push origin KDE/4.6:KDE/4.6

The next step is to apply the bug fix to the unstable master branch. First check the master branch back out and update it:

git checkout master
git pull --rebase

Next, Git makes it easy to apply the existing bug fix from the stable branch by using the cherry-pick command:

git cherry-pick -x -e <sha5 of stable commit>

This will allow you to edit the commit message as required before the change is committed. If the patch does not apply cleanly a message will appear and the changes will not be committed. You will then have to edit the changes and finish the commit manually.

Once cleanly applied and committed you can build and test the change, then push them to the central code repository:

git pull --rebase
git push origin master:master

Development/Git/Simple Workflow

2011-06-13T09:15:12Z

Odysseus: /* Local Bug Fixing */

DANGER WILL ROBINSON!!! THIS IS AN INCOMPLETE DRAFT!!!

= Simple Workflow =

This workflow is designed to be as close as possible to the KDE SVN Workflow. It is only recommended to be used for the first week or two of using Git with KDE while you become familiar with the basic Git commands. Once comfortable with the basic commands you should then move on to the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

In particular this workflow will not use git branches, merging or any remote features, all feature development work will be in the local master branch (the Git name for trunk).

More detailed information can be found on the main [[Development/Git|KDE Git page]], in particular the [[Development/Git#Git_for_SVN_Users|Git for Subversion Users]] section. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow all the instructions on the [[Development/Git/Configuration|KDE Git Configuration]] page, the instructions given below assume you are using the standard configuration.

=== Clone your repository ===

You need to copy your central code repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>
cd <project>

For example to clone kdelibs:

git clone kde:kdelibs
cd kdelibs

See the [[Getting_Started/Build/Environment#Source_Path|KDE Build Environment]] page for advice on structuring your source directory.

If you have a slow or intermittent internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the [https://projects.kde.org/projects projects.kde.org] Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Local Feature Development ==

This section documents the basic workflow for developing a new feature for the master unstable branch (aka trunk in subversion). You will first make local code changes and commit them in your local repository before pushing them to the central code repository.

=== Making Local Changes and Commits ===

Changing and building code itself is no different from when using subversion, but how changed files are managed and committed is very different, as are the names and commands used. There are two key differences:
* Locally modified files can have different states that determine whether they get committed or not.
* Committing code is only local, it does not push your changes to the central repository which requires an extra step.

Files in a git repository can be in various states:
* Untracked: Files in your local repository directory that Git is not tracking changes to and are not in the central repository.
* Tracked: Files that git tracks changes to.
* Unstaged: Tracked files that have had modifications to them but have not yet been staged or committed.
* Staged: Tracked files that have had modifications made to them and have been marked to be included in the next commit
* Committed: Files that git is tracking and that have been included in a local commit that may or may not be included in the central repository.

Note that different versions of a file can be in the Untracked and Tracked states at the same time.

This difference between staged and unstaged changes allows you to choose what changes you want in each commit.

To see what the current status of your local repository is:

git status

This will show you the status as follows;

# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: src/kstagedfile.h
#
# Changed but not updated:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: src/kchangedfile.h
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# src/kuntrackedfile.txt

To add a changed file to the staging area, or to add a new file to be tracked by the repository:

git add <filename>

To delete a file from the repository and add the deletion to the staging area:

git rm <filename>

To reset a staged file to be unstaged but without losing your changes:

git reset HEAD <filename>

To reset an unstaged file to the currently committed version and irretrievably throw away your changes:

git checkout <filename>

The git commit command differs from the svn commit command in only creating a commit in your local clone of the repository, it does not merge the changes into the central repository. This allows you to queue up a series of small changes before merging them into the central repository. This local commit history can [[Development/Git/Recipes#Interactive_Rebasing|also be modified]] before you finally do push the changes.

The git commit command adds all files in the staged state into a new commit:

git commit

If you have only changed tracked files then you can automatically add all tracked files that have been changed into staging and commit all the staged files in one command:

git commit -a

=== Seeing What You Changed ===

To see a list of what files have been changed but not yet committed:

git status

To see what code changes have been made but not yet staged:

git diff
git diff <filename>

To see what code changes have been staged but not committed:

git diff --staged
git diff --staged <filename>

To see all the commits made:

git log

To see what changes were made in a commit:

git show <sha5>

The Git diff, log and show commands have many options for changing what is shown. In particular diff can show the difference in a file between any two commits.

=== Pushing Your Changes To The Central Repository ===

When you are ready to push all your local commits to the central repository, you first need to update to the latest version of the master code in the central repository:

git pull --rebase

This will update the underlying master code and apply your commits on the top of the latest version of the central repository, this is known as a rebase. Normally the rebase should apply cleanly, but sometimes there will be a conflict which you will need to resolve before you can complete applying your commits. There will be instructions given by git on how to complete the commit if required [TODO: get a copy of the output text].

Note that you cannot rebase if you have uncommitted changes. If you need to rebase but have changes that you don't want to commit, then you will need to [[Development/Git/Recipes#Stashing_Changes|stash the changes]].

Depending on how much the underlying master code has changed you may want to rebuild and test the code after doing the rebase, before doing a final rebase. It is recommended to do regular rebase's between commits to keep the possibility of conflicts to a minimum.

Once your local commits have been cleanly reapplied you can push your changes to the central repository:

git push origin master:master

Git will report if the push was successful or explain why it failed.

== Local Bug Fixing ==

If your bug fix is only for unstable master then no special actions are required, just follow the same steps as the feature development workflow above.

If your bug fix is for a stable branch then this cannot be done without using git branches. The steps required will be given below but not explained in any detail. If possible it is recommended you wait until you are familiar with using the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

The steps detailed below are very inefficient as they use the same build tree and environment for unstable and stable which may cause a lot of rebuilding. A more efficient method is detailed in the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

First, find out the name of the stable branch you want to bug fix:

git branch -r

This will list all the branches on the central repository, for example kdelibs includes the following branches:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs which we will use for this example.

Next, create a local branch pointing to the stable release branch you want to bug fix:

git branch --track <local-branch> <remote-branch>
git checkout <local-branch>

For example, to create a kdelibs 4.6 stable branch:

git branch --track KDE/4.6 origin/KDE/4.6
git checkout KDE/4.6

If you have previously created the stable branch and want to do a new bug fix, then simply check it out again and update it:

git checkout <local-branch>
git pull --rebase

Now make your required changes to the code, build and test. Once done commit the code changes to your local repository, remembering to include the BUG: and FIXED-IN: keywords in the commit message:

git commit -a

Make a note of the sha5 of the commit as you will need it later to copy the commit to the unstable master branch.

Now you can push your changes into the central code repository:

git pull --rebase
git push origin KDE/4.6:KDE/4.6

The next step is to apply the bug fix to the unstable master branch. First check the master branch back out and update it:

git checkout master
git pull --rebase

Next, Git makes it easy to apply the existing bug fix from the stable branch by using the cherry-pick command:

git cherry-pick -x -e <sha5 of stable commit>

This will allow you to edit the commit message as required before the change is committed. If the patch does not apply cleanly a message will appear and the changes will not be committed. You will then have to edit the changes and finish the commit manually.

Once cleanly applied and committed you can build and test the change, then merge them into the central code repository:

git pull --rebase
git push origin master:master

Development/Git/Simple Workflow

2011-06-13T09:11:02Z

Odysseus: /* Pushing Your Changes To The Central Repository */

DANGER WILL ROBINSON!!! THIS IS AN INCOMPLETE DRAFT!!!

= Simple Workflow =

This workflow is designed to be as close as possible to the KDE SVN Workflow. It is only recommended to be used for the first week or two of using Git with KDE while you become familiar with the basic Git commands. Once comfortable with the basic commands you should then move on to the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

In particular this workflow will not use git branches, merging or any remote features, all feature development work will be in the local master branch (the Git name for trunk).

More detailed information can be found on the main [[Development/Git|KDE Git page]], in particular the [[Development/Git#Git_for_SVN_Users|Git for Subversion Users]] section. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow all the instructions on the [[Development/Git/Configuration|KDE Git Configuration]] page, the instructions given below assume you are using the standard configuration.

=== Clone your repository ===

You need to copy your central code repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>
cd <project>

For example to clone kdelibs:

git clone kde:kdelibs
cd kdelibs

See the [[Getting_Started/Build/Environment#Source_Path|KDE Build Environment]] page for advice on structuring your source directory.

If you have a slow or intermittent internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the [https://projects.kde.org/projects projects.kde.org] Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Local Feature Development ==

This section documents the basic workflow for developing a new feature for the master unstable branch (aka trunk in subversion). You will first make local code changes and commit them in your local repository before pushing them to the central code repository.

=== Making Local Changes and Commits ===

Changing and building code itself is no different from when using subversion, but how changed files are managed and committed is very different, as are the names and commands used. There are two key differences:
* Locally modified files can have different states that determine whether they get committed or not.
* Committing code is only local, it does not push your changes to the central repository which requires an extra step.

Files in a git repository can be in various states:
* Untracked: Files in your local repository directory that Git is not tracking changes to and are not in the central repository.
* Tracked: Files that git tracks changes to.
* Unstaged: Tracked files that have had modifications to them but have not yet been staged or committed.
* Staged: Tracked files that have had modifications made to them and have been marked to be included in the next commit
* Committed: Files that git is tracking and that have been included in a local commit that may or may not be included in the central repository.

Note that different versions of a file can be in the Untracked and Tracked states at the same time.

This difference between staged and unstaged changes allows you to choose what changes you want in each commit.

To see what the current status of your local repository is:

git status

This will show you the status as follows;

# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: src/kstagedfile.h
#
# Changed but not updated:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: src/kchangedfile.h
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# src/kuntrackedfile.txt

To add a changed file to the staging area, or to add a new file to be tracked by the repository:

git add <filename>

To delete a file from the repository and add the deletion to the staging area:

git rm <filename>

To reset a staged file to be unstaged but without losing your changes:

git reset HEAD <filename>

To reset an unstaged file to the currently committed version and irretrievably throw away your changes:

git checkout <filename>

The git commit command differs from the svn commit command in only creating a commit in your local clone of the repository, it does not merge the changes into the central repository. This allows you to queue up a series of small changes before merging them into the central repository. This local commit history can [[Development/Git/Recipes#Interactive_Rebasing|also be modified]] before you finally do push the changes.

The git commit command adds all files in the staged state into a new commit:

git commit

If you have only changed tracked files then you can automatically add all tracked files that have been changed into staging and commit all the staged files in one command:

git commit -a

=== Seeing What You Changed ===

To see a list of what files have been changed but not yet committed:

git status

To see what code changes have been made but not yet staged:

git diff
git diff <filename>

To see what code changes have been staged but not committed:

git diff --staged
git diff --staged <filename>

To see all the commits made:

git log

To see what changes were made in a commit:

git show <sha5>

The Git diff, log and show commands have many options for changing what is shown. In particular diff can show the difference in a file between any two commits.

=== Pushing Your Changes To The Central Repository ===

When you are ready to push all your local commits to the central repository, you first need to update to the latest version of the master code in the central repository:

git pull --rebase

This will update the underlying master code and apply your commits on the top of the latest version of the central repository, this is known as a rebase. Normally the rebase should apply cleanly, but sometimes there will be a conflict which you will need to resolve before you can complete applying your commits. There will be instructions given by git on how to complete the commit if required [TODO: get a copy of the output text].

Note that you cannot rebase if you have uncommitted changes. If you need to rebase but have changes that you don't want to commit, then you will need to [[Development/Git/Recipes#Stashing_Changes|stash the changes]].

Depending on how much the underlying master code has changed you may want to rebuild and test the code after doing the rebase, before doing a final rebase. It is recommended to do regular rebase's between commits to keep the possibility of conflicts to a minimum.

Once your local commits have been cleanly reapplied you can push your changes to the central repository:

git push origin master:master

Git will report if the push was successful or explain why it failed.

== Local Bug Fixing ==

If your bug fix is only for unstable master then no special actions are required, just follow the same steps as the feature development workflow above.

If your bug fix is for a stable branch then this cannot be done without using git branches. The steps required will be given below but not explained in any detail. If possible it is recommended you wait until you are familiar with using the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

The steps detailed below are very inefficient as they use the same build tree and environment for unstable and stable which may cause a lot of rebuilding. A more efficient method is detailed in the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

First, find out the name of the stable branch you want to bug fix:

git branch -r

This will list all the branches on the central repository, for example kdelibs includes the following branches:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs which we will use for this example.

Next, create a local branch pointing to the stable release branch you want to bug fix:

git branch --track KDE/4.6 origin/KDE/4.6
git checkout KDE/4.6

If you have previously created the stable branch and want to do a new bug fix, then simply check it out again and update it:

git checkout KDE/4.6
git pull --rebase

Now make your required changes to the code, build and test. Once done commit the code changes to your local repository, remembering to include the BUG: and FIXED-IN: keywords in the commit message:

git commit -a

Make a note of the sha5 of the commit as you will need it later to copy the commit to the unstable master branch.

Now you can push your changes into the central code repository:

git pull --rebase
git push origin KDE/4.6:KDE/4.6

The next step is to apply the bug fix to the unstable master branch. First check the master branch back out and update it:

git checkout master
git pull --rebase

Next, Git makes it easy to apply the existing bug fix from the stable branch by using the cherry-pick command:

git cherry-pick -x -e <sha5 of stable commit>

This will allow you to edit the commit message as required before the change is committed. If the patch does not apply cleanly a message will appear and the changes will not be committed. You will then have to edit the changes and finish the commit manually.

Once cleanly applied and committed you can build and test the change, then merge them into the central code repository:

git pull --rebase
git push origin master:master

Development/Git/Feature Branch Workflow

2011-06-13T08:10:58Z

Odysseus: /* Remote Feature Development */

THIS IS A DRAFT, DO NOT USE!

= Feature Branch Workflow =

This Git Workflow is the recommended KDE Git Workflow for smaller projects where new features are developed in local and/or remote feature branches before being reviewed and merged back into the master branch.

This workflow is designed to be used after initial use of the [[Development/Git/Simple_Workflow|Simple Workflow]]. It is assumed you have read and mastered the basic concepts as outlined in that Workflow, such as unstaged and staged changes, committing, rebasing and pushing.

Note that each module may choose to adopt a more complex workflow, in particular the Integration Branch Workflow, and you should check with your modules maintainers if this is the case.

More detailed information can be found on the main [[Development/Git|KDE Git page]]. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

See the [[Development/Git/Simple_Workflow#Set-up|Simple Workflow Set-up]] section for instructions on configuring Git and Cloning your Repository

== Local Feature Development ==

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

=== Create a Local Work Branch ===

To see what local branches you have:

git branch

This will initially appear as follows, with the * indicating your current working branch:

* master

To see all local and remote branches:

git branch -a

This will initially look something like:

* master
remotes/origin/HEAD -> origin/master
remotes/origin/KDE/4.5
remotes/origin/KDE/4.6
remotes/origin/kdecore/klocale-win
remotes/origin/kdeui/kdatetimeedit

To create a new local branch:

git branch <new-branch>

Now running <tt>git branch</tt> will show:

* master
my-new-branch

To change to the new branch to work on it:

git checkout <new-branch>

Now running <tt>git branch</tt> will show:

master
* my-new-branch

This sequence will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' a remote branch and is recommended for most work branches:

git branch --track <local-branch> <remote-branch>

For example to develop a new feature called 'bar' based on the central repository master branch:

git branch --track new-bar-feature origin/master

=== Making Changes ===

You can now make [[Development/Git/Simple_Workflow#Making_Local_Changes_and_Commits|local changes and commits]], and [[Development/Git/Simple_Workflow#Pushing_Your_Changes_To_The_Central_Repository|push them to the central repository]] exactly as described in the [[Development/Git/Simple_Workflow|Simple Workflow]].

=== Deleting Local Branches ===

Once you have finished with a local feature branch and pushed all your commits to the central repository you can delete the local branch if you no longer require it.

First, you have to change to a different branch:

git checkout master

Then you can delete the feature branch:

git -d <local-branch>

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

The main disadvantage of local feature branch development is no-one else can see your code changes or help you until the finished feature is pushed to the central repository.

TODO: Finish this.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, kdelibs includes the following branches on the central repository:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs.

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

In the [[Development/Git/Simple_Workflow#Local_Bug_Fixing|Simple Workflow bug fixing]] section we describe a simple way to perform bug fixes for both stable and unstable branches in the same repository clone.

The basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

One alternative is to have two separate clones using two separate build environments, but this wastes disk space and causes problems with keeping the separate clones in sync.

A better alternative is to use the [[Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for the stable and unstable branches using the same repository clone. This depends on you setting different up KDE Environments for the separate builds.

TODO: Finish this.

Development/Git/Feature Branch Workflow

2011-06-12T21:51:21Z

Odysseus: /* Local Bug Fixing */

THIS IS A DRAFT, DO NOT USE!

= Feature Branch Workflow =

This Git Workflow is the recommended KDE Git Workflow for smaller projects where new features are developed in local and/or remote feature branches before being reviewed and merged back into the master branch.

This workflow is designed to be used after initial use of the [[Development/Git/Simple_Workflow|Simple Workflow]]. It is assumed you have read and mastered the basic concepts as outlined in that Workflow, such as unstaged and staged changes, committing, rebasing and pushing.

Note that each module may choose to adopt a more complex workflow, in particular the Integration Branch Workflow, and you should check with your modules maintainers if this is the case.

More detailed information can be found on the main [[Development/Git|KDE Git page]]. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

See the [[Development/Git/Simple_Workflow#Set-up|Simple Workflow Set-up]] section for instructions on configuring Git and Cloning your Repository

== Local Feature Development ==

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

=== Create a Local Work Branch ===

To see what local branches you have:

git branch

This will initially appear as follows, with the * indicating your current working branch:

* master

To see all local and remote branches:

git branch -a

This will initially look something like:

* master
remotes/origin/HEAD -> origin/master
remotes/origin/KDE/4.5
remotes/origin/KDE/4.6
remotes/origin/kdecore/klocale-win
remotes/origin/kdeui/kdatetimeedit

To create a new local branch:

git branch <new-branch>

Now running <tt>git branch</tt> will show:

* master
my-new-branch

To change to the new branch to work on it:

git checkout <new-branch>

Now running <tt>git branch</tt> will show:

master
* my-new-branch

This sequence will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' a remote branch and is recommended for most work branches:

git branch --track <local-branch> <remote-branch>

For example to develop a new feature called 'bar' based on the central repository master branch:

git branch --track new-bar-feature origin/master

=== Making Changes ===

You can now make [[Development/Git/Simple_Workflow#Making_Local_Changes_and_Commits|local changes and commits]], and [[Development/Git/Simple_Workflow#Pushing_Your_Changes_To_The_Central_Repository|push them to the central repository]] exactly as described in the [[Development/Git/Simple_Workflow|Simple Workflow]].

=== Deleting Local Branches ===

Once you have finished with a local feature branch and pushed all your commits to the central repository you can delete the local branch if you no longer require it.

First, you have to change to a different branch:

git checkout master

Then you can delete the feature branch:

git -d <local-branch>

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

TODO: Finish this.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, kdelibs includes the following branches on the central repository:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs.

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

In the [[Development/Git/Simple_Workflow#Local_Bug_Fixing|Simple Workflow bug fixing]] section we describe a simple way to perform bug fixes for both stable and unstable branches in the same repository clone.

The basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

One alternative is to have two separate clones using two separate build environments, but this wastes disk space and causes problems with keeping the separate clones in sync.

A better alternative is to use the [[Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for the stable and unstable branches using the same repository clone. This depends on you setting different up KDE Environments for the separate builds.

TODO: Finish this.

Development/Git/Feature Branch Workflow

2011-06-12T21:50:59Z

Odysseus: /* Remote Feature Development */

THIS IS A DRAFT, DO NOT USE!

= Feature Branch Workflow =

This Git Workflow is the recommended KDE Git Workflow for smaller projects where new features are developed in local and/or remote feature branches before being reviewed and merged back into the master branch.

This workflow is designed to be used after initial use of the [[Development/Git/Simple_Workflow|Simple Workflow]]. It is assumed you have read and mastered the basic concepts as outlined in that Workflow, such as unstaged and staged changes, committing, rebasing and pushing.

Note that each module may choose to adopt a more complex workflow, in particular the Integration Branch Workflow, and you should check with your modules maintainers if this is the case.

More detailed information can be found on the main [[Development/Git|KDE Git page]]. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

See the [[Development/Git/Simple_Workflow#Set-up|Simple Workflow Set-up]] section for instructions on configuring Git and Cloning your Repository

== Local Feature Development ==

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

=== Create a Local Work Branch ===

To see what local branches you have:

git branch

This will initially appear as follows, with the * indicating your current working branch:

* master

To see all local and remote branches:

git branch -a

This will initially look something like:

* master
remotes/origin/HEAD -> origin/master
remotes/origin/KDE/4.5
remotes/origin/KDE/4.6
remotes/origin/kdecore/klocale-win
remotes/origin/kdeui/kdatetimeedit

To create a new local branch:

git branch <new-branch>

Now running <tt>git branch</tt> will show:

* master
my-new-branch

To change to the new branch to work on it:

git checkout <new-branch>

Now running <tt>git branch</tt> will show:

master
* my-new-branch

This sequence will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' a remote branch and is recommended for most work branches:

git branch --track <local-branch> <remote-branch>

For example to develop a new feature called 'bar' based on the central repository master branch:

git branch --track new-bar-feature origin/master

=== Making Changes ===

You can now make [[Development/Git/Simple_Workflow#Making_Local_Changes_and_Commits|local changes and commits]], and [[Development/Git/Simple_Workflow#Pushing_Your_Changes_To_The_Central_Repository|push them to the central repository]] exactly as described in the [[Development/Git/Simple_Workflow|Simple Workflow]].

=== Deleting Local Branches ===

Once you have finished with a local feature branch and pushed all your commits to the central repository you can delete the local branch if you no longer require it.

First, you have to change to a different branch:

git checkout master

Then you can delete the feature branch:

git -d <local-branch>

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

TODO: Finish this.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, kdelibs includes the following branches on the central repository:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs.

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

In the [[Development/Git/Simple_Workflow#Local_Bug_Fixing|Simple Workflow bug fixing]] section we describe a simple way to perform bug fixes for both stable and unstable branches in the same repository clone.

The basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

One alternative is to have two separate clones using two separate build environments, but this wastes disk space and causes problems with keeping the separate clones in sync.

A better alternative is to use the [[Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for the stable and unstable branches using the same repository clone. This depends on you setting different up KDE Environments for the separate builds.

Development/Git/Feature Branch Workflow

2011-06-12T21:42:53Z

Odysseus: /* Local Bug Fixing */

THIS IS A DRAFT, DO NOT USE!

= Feature Branch Workflow =

This Git Workflow is the recommended KDE Git Workflow for smaller projects where new features are developed in local and/or remote feature branches before being reviewed and merged back into the master branch.

This workflow is designed to be used after initial use of the [[Development/Git/Simple_Workflow|Simple Workflow]]. It is assumed you have read and mastered the basic concepts as outlined in that Workflow, such as unstaged and staged changes, committing, rebasing and pushing.

Note that each module may choose to adopt a more complex workflow, in particular the Integration Branch Workflow, and you should check with your modules maintainers if this is the case.

More detailed information can be found on the main [[Development/Git|KDE Git page]]. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

See the [[Development/Git/Simple_Workflow#Set-up|Simple Workflow Set-up]] section for instructions on configuring Git and Cloning your Repository

== Local Feature Development ==

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

=== Create a Local Work Branch ===

To see what local branches you have:

git branch

This will initially appear as follows, with the * indicating your current working branch:

* master

To see all local and remote branches:

git branch -a

This will initially look something like:

* master
remotes/origin/HEAD -> origin/master
remotes/origin/KDE/4.5
remotes/origin/KDE/4.6
remotes/origin/kdecore/klocale-win
remotes/origin/kdeui/kdatetimeedit

To create a new local branch:

git branch <new-branch>

Now running <tt>git branch</tt> will show:

* master
my-new-branch

To change to the new branch to work on it:

git checkout <new-branch>

Now running <tt>git branch</tt> will show:

master
* my-new-branch

This sequence will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' a remote branch and is recommended for most work branches:

git branch --track <local-branch> <remote-branch>

For example to develop a new feature called 'bar' based on the central repository master branch:

git branch --track new-bar-feature origin/master

=== Making Changes ===

You can now make [[Development/Git/Simple_Workflow#Making_Local_Changes_and_Commits|local changes and commits]], and [[Development/Git/Simple_Workflow#Pushing_Your_Changes_To_The_Central_Repository|push them to the central repository]] exactly as described in the [[Development/Git/Simple_Workflow|Simple Workflow]].

=== Deleting Local Branches ===

Once you have finished with a local feature branch and pushed all your commits to the central repository you can delete the local branch if you no longer require it.

First, you have to change to a different branch:

git checkout master

Then you can delete the feature branch:

git -d <local-branch>

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, kdelibs includes the following branches on the central repository:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs.

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

In the [[Development/Git/Simple_Workflow#Local_Bug_Fixing|Simple Workflow bug fixing]] section we describe a simple way to perform bug fixes for both stable and unstable branches in the same repository clone.

The basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

One alternative is to have two separate clones using two separate build environments, but this wastes disk space and causes problems with keeping the separate clones in sync.

A better alternative is to use the [[Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for the stable and unstable branches using the same repository clone. This depends on you setting different up KDE Environments for the separate builds.

Development/Git/Feature Branch Workflow

2011-06-12T21:42:29Z

Odysseus: /* Local Bug Fixing */

THIS IS A DRAFT, DO NOT USE!

= Feature Branch Workflow =

This Git Workflow is the recommended KDE Git Workflow for smaller projects where new features are developed in local and/or remote feature branches before being reviewed and merged back into the master branch.

This workflow is designed to be used after initial use of the [[Development/Git/Simple_Workflow|Simple Workflow]]. It is assumed you have read and mastered the basic concepts as outlined in that Workflow, such as unstaged and staged changes, committing, rebasing and pushing.

Note that each module may choose to adopt a more complex workflow, in particular the Integration Branch Workflow, and you should check with your modules maintainers if this is the case.

More detailed information can be found on the main [[Development/Git|KDE Git page]]. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

See the [[Development/Git/Simple_Workflow#Set-up|Simple Workflow Set-up]] section for instructions on configuring Git and Cloning your Repository

== Local Feature Development ==

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

=== Create a Local Work Branch ===

To see what local branches you have:

git branch

This will initially appear as follows, with the * indicating your current working branch:

* master

To see all local and remote branches:

git branch -a

This will initially look something like:

* master
remotes/origin/HEAD -> origin/master
remotes/origin/KDE/4.5
remotes/origin/KDE/4.6
remotes/origin/kdecore/klocale-win
remotes/origin/kdeui/kdatetimeedit

To create a new local branch:

git branch <new-branch>

Now running <tt>git branch</tt> will show:

* master
my-new-branch

To change to the new branch to work on it:

git checkout <new-branch>

Now running <tt>git branch</tt> will show:

master
* my-new-branch

This sequence will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' a remote branch and is recommended for most work branches:

git branch --track <local-branch> <remote-branch>

For example to develop a new feature called 'bar' based on the central repository master branch:

git branch --track new-bar-feature origin/master

=== Making Changes ===

You can now make [[Development/Git/Simple_Workflow#Making_Local_Changes_and_Commits|local changes and commits]], and [[Development/Git/Simple_Workflow#Pushing_Your_Changes_To_The_Central_Repository|push them to the central repository]] exactly as described in the [[Development/Git/Simple_Workflow|Simple Workflow]].

=== Deleting Local Branches ===

Once you have finished with a local feature branch and pushed all your commits to the central repository you can delete the local branch if you no longer require it.

First, you have to change to a different branch:

git checkout master

Then you can delete the feature branch:

git -d <local-branch>

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, kdelibs includes the following branches on the central repository:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs.

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

In the [[Development/Git/Simple_Workflow#Local_Bug_Fixing|Simple Workflow bug fixing]] section we describe a simple way to perform bug fixes for both stable and unstable branches in the same repository clone.

The basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

One alternative is to have two separate clones using two separate build environments, but this wastes disk space and causes problems with keeping the separate clones in sync.

A better alternative is to use the [[http://techbase.kde.org/Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for the stable and unstable branches using the same repository clone. This depends on you setting different up KDE Environments for the separate builds.

Development/Git/Feature Branch Workflow

2011-06-12T21:02:05Z

Odysseus: /* Local Bug Fixing */

THIS IS A DRAFT, DO NOT USE!

= Feature Branch Workflow =

This Git Workflow is the recommended KDE Git Workflow for smaller projects where new features are developed in local and/or remote feature branches before being reviewed and merged back into the master branch.

This workflow is designed to be used after initial use of the [[Development/Git/Simple_Workflow|Simple Workflow]]. It is assumed you have read and mastered the basic concepts as outlined in that Workflow, such as unstaged and staged changes, committing, rebasing and pushing.

Note that each module may choose to adopt a more complex workflow, in particular the Integration Branch Workflow, and you should check with your modules maintainers if this is the case.

More detailed information can be found on the main [[Development/Git|KDE Git page]]. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

See the [[Development/Git/Simple_Workflow#Set-up|Simple Workflow Set-up]] section for instructions on configuring Git and Cloning your Repository

== Local Feature Development ==

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

=== Create a Local Work Branch ===

To see what local branches you have:

git branch

This will initially appear as follows, with the * indicating your current working branch:

* master

To see all local and remote branches:

git branch -a

This will initially look something like:

* master
remotes/origin/HEAD -> origin/master
remotes/origin/KDE/4.5
remotes/origin/KDE/4.6
remotes/origin/kdecore/klocale-win
remotes/origin/kdeui/kdatetimeedit

To create a new local branch:

git branch <new-branch>

Now running <tt>git branch</tt> will show:

* master
my-new-branch

To change to the new branch to work on it:

git checkout <new-branch>

Now running <tt>git branch</tt> will show:

master
* my-new-branch

This sequence will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' a remote branch and is recommended for most work branches:

git branch --track <local-branch> <remote-branch>

For example to develop a new feature called 'bar' based on the central repository master branch:

git branch --track new-bar-feature origin/master

=== Making Changes ===

You can now make [[Development/Git/Simple_Workflow#Making_Local_Changes_and_Commits|local changes and commits]], and [[Development/Git/Simple_Workflow#Pushing_Your_Changes_To_The_Central_Repository|push them to the central repository]] exactly as described in the [[Development/Git/Simple_Workflow|Simple Workflow]].

=== Deleting Local Branches ===

Once you have finished with a local feature branch and pushed all your commits to the central repository you can delete the local branch if you no longer require it.

First, you have to change to a different branch:

git checkout master

Then you can delete the feature branch:

git -d <local-branch>

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, kdelibs includes the following branches on the central repository:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs.

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

In the [[Development/Git/Simple_Workflow#Local_Bug_Fixing|Simple Workflow bug fixing]] section we describe a simple way to perform bug fixes for both stable and unstable branches in the same repository clone.

The basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

This workflow uses the [[http://techbase.kde.org/Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for stable and unstable branches. This depends on you setting different up KDE Environments for the separate builds.

Development/Git/Feature Branch Workflow

2011-06-12T20:37:44Z

Odysseus: /* Making Changes */

THIS IS A DRAFT, DO NOT USE!

= Feature Branch Workflow =

This Git Workflow is the recommended KDE Git Workflow for smaller projects where new features are developed in local and/or remote feature branches before being reviewed and merged back into the master branch.

This workflow is designed to be used after initial use of the [[Development/Git/Simple_Workflow|Simple Workflow]]. It is assumed you have read and mastered the basic concepts as outlined in that Workflow, such as unstaged and staged changes, committing, rebasing and pushing.

Note that each module may choose to adopt a more complex workflow, in particular the Integration Branch Workflow, and you should check with your modules maintainers if this is the case.

More detailed information can be found on the main [[Development/Git|KDE Git page]]. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

See the [[Development/Git/Simple_Workflow#Set-up|Simple Workflow Set-up]] section for instructions on configuring Git and Cloning your Repository

== Local Feature Development ==

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

=== Create a Local Work Branch ===

To see what local branches you have:

git branch

This will initially appear as follows, with the * indicating your current working branch:

* master

To see all local and remote branches:

git branch -a

This will initially look something like:

* master
remotes/origin/HEAD -> origin/master
remotes/origin/KDE/4.5
remotes/origin/KDE/4.6
remotes/origin/kdecore/klocale-win
remotes/origin/kdeui/kdatetimeedit

To create a new local branch:

git branch <new-branch>

Now running <tt>git branch</tt> will show:

* master
my-new-branch

To change to the new branch to work on it:

git checkout <new-branch>

Now running <tt>git branch</tt> will show:

master
* my-new-branch

This sequence will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' a remote branch and is recommended for most work branches:

git branch --track <local-branch> <remote-branch>

For example to develop a new feature called 'bar' based on the central repository master branch:

git branch --track new-bar-feature origin/master

=== Making Changes ===

You can now make [[Development/Git/Simple_Workflow#Making_Local_Changes_and_Commits|local changes and commits]], and [[Development/Git/Simple_Workflow#Pushing_Your_Changes_To_The_Central_Repository|push them to the central repository]] exactly as described in the [[Development/Git/Simple_Workflow|Simple Workflow]].

=== Deleting Local Branches ===

Once you have finished with a local feature branch and pushed all your commits to the central repository you can delete the local branch if you no longer require it.

First, you have to change to a different branch:

git checkout master

Then you can delete the feature branch:

git -d <local-branch>

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, kdelibs includes the following branches on the central repository:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs.

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

Two workflow's are described here, a basic workflow for small apps or where bug-fixes are infrequent, and an advanced workflow for larger apps or more frequent bug-fixes.

=== Basic Bug Fix Workflow ===

To make bug fixes on the 2.0 release you could simply checkout a local copy of the origin/release/2.0 branch and make you bug fixes there:

git branch --track bug-fix-2.0 origin/release/2.0
git checkout bug-fix-2.0
<make changes, build, test>
git commit -a
git push origin bug-fix-2.0:release/2.0
git branch --track bug-fix-master origin/master
git checkout bug-fix-master
git cherry-pick -x -e <sha5 of stable commit>
<build, test>
git push origin bug-fix-master:master

=== Advanced Bug Fix Workflow ===

the basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

This workflow uses the [[http://techbase.kde.org/Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for stable and unstable branches. This depends on you setting different up KDE Environments for the separate builds.

Development/Git/Feature Branch Workflow

2011-06-12T19:57:56Z

Odysseus: /* Local Feature Development */

THIS IS A DRAFT, DO NOT USE!

= Feature Branch Workflow =

This Git Workflow is the recommended KDE Git Workflow for smaller projects where new features are developed in local and/or remote feature branches before being reviewed and merged back into the master branch.

This workflow is designed to be used after initial use of the [[Development/Git/Simple_Workflow|Simple Workflow]]. It is assumed you have read and mastered the basic concepts as outlined in that Workflow, such as unstaged and staged changes, committing, rebasing and pushing.

Note that each module may choose to adopt a more complex workflow, in particular the Integration Branch Workflow, and you should check with your modules maintainers if this is the case.

More detailed information can be found on the main [[Development/Git|KDE Git page]]. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

See the [[Development/Git/Simple_Workflow#Set-up|Simple Workflow Set-up]] section for instructions on configuring Git and Cloning your Repository

== Local Feature Development ==

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

=== Create a Local Work Branch ===

To see what local branches you have:

git branch

This will initially appear as follows, with the * indicating your current working branch:

* master

To see all local and remote branches:

git branch -a

This will initially look something like:

* master
remotes/origin/HEAD -> origin/master
remotes/origin/KDE/4.5
remotes/origin/KDE/4.6
remotes/origin/kdecore/klocale-win
remotes/origin/kdeui/kdatetimeedit

To create a new local branch:

git branch <new-branch>

Now running <tt>git branch</tt> will show:

* master
my-new-branch

To change to the new branch to work on it:

git checkout <new-branch>

Now running <tt>git branch</tt> will show:

master
* my-new-branch

This sequence will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' a remote branch and is recommended for most work branches:

git branch --track <local-branch> <remote-branch>

For example to develop a new feature called 'bar' based on the central repository master branch:

git branch --track new-bar-feature origin/master

=== Making Changes ===

You can now make [[Development/Git/Simple_Workflow#Making_Local_Changes_and_Commits|local changes and commits]], and [[Development/Git/Simple_Workflow#Pushing_Your_Changes_To_The_Central_Repository|push them to the central repository]] exactly as described in the [[Development/Git/Simple_Workflow|Simple Workflow]].

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, kdelibs includes the following branches on the central repository:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs.

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

Two workflow's are described here, a basic workflow for small apps or where bug-fixes are infrequent, and an advanced workflow for larger apps or more frequent bug-fixes.

=== Basic Bug Fix Workflow ===

To make bug fixes on the 2.0 release you could simply checkout a local copy of the origin/release/2.0 branch and make you bug fixes there:

git branch --track bug-fix-2.0 origin/release/2.0
git checkout bug-fix-2.0
<make changes, build, test>
git commit -a
git push origin bug-fix-2.0:release/2.0
git branch --track bug-fix-master origin/master
git checkout bug-fix-master
git cherry-pick -x -e <sha5 of stable commit>
<build, test>
git push origin bug-fix-master:master

=== Advanced Bug Fix Workflow ===

the basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

This workflow uses the [[http://techbase.kde.org/Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for stable and unstable branches. This depends on you setting different up KDE Environments for the separate builds.

Development/Git/Feature Branch Workflow

2011-06-12T19:56:56Z

Odysseus: /* Local Feature Development */

THIS IS A DRAFT, DO NOT USE!

= Feature Branch Workflow =

This Git Workflow is the recommended KDE Git Workflow for smaller projects where new features are developed in local and/or remote feature branches before being reviewed and merged back into the master branch.

This workflow is designed to be used after initial use of the [[Development/Git/Simple_Workflow|Simple Workflow]]. It is assumed you have read and mastered the basic concepts as outlined in that Workflow, such as unstaged and staged changes, committing, rebasing and pushing.

Note that each module may choose to adopt a more complex workflow, in particular the Integration Branch Workflow, and you should check with your modules maintainers if this is the case.

More detailed information can be found on the main [[Development/Git|KDE Git page]]. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

See the [[Development/Git/Simple_Workflow#Set-up|Simple Workflow Set-up]] section for instructions on configuring Git and Cloning your Repository

== Local Feature Development ==

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

=== Create a Local Work Branch ===

To see what local branches you have:

git branch

This will initially appear as follows, with the * indicating your current working branch:

* master

To see all local and remote branches:

git branch -a

This will initially look something like:

* master
remotes/origin/HEAD -> origin/master
remotes/origin/KDE/4.5
remotes/origin/KDE/4.6
remotes/origin/kdecore/klocale-win
remotes/origin/kdeui/kdatetimeedit

To create a new local branch:

git branch <new-branch>

Now running <tt>git branch</tt> will show:

* master
my-new-branch

To change to the new branch to work on it:

git checkout <new-branch>

Now running <tt>git branch</tt> will show:

master
* my-new-branch

This sequence will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' a remote branch and is recommended for most work branches:

git branch --track <local-branch> <remote-branch>

For example to develop a new feature called 'bar' based on the central repository master branch:

git branch --track new-bar-feature origin/master

=== Making Changes ===

You can now make [[Development/Git/Simple_Workflow#Making_Local_Changes_and_Commits|local changes and commits]], and [[Development/Git/Simple_Workflow#Pushing_Your_Changes_To_The_Central_Repository|push them to the central repository]] exactly as described in the [[Development/Git/Simple_Workflow|Simple Workflow]].

== Local Feature Development ==

This example workflow is for locally working on new features in unstable branch and pushing them to the central repository.

This workflow is only recommended for small features or where you are the only developer on a project.

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, kdelibs includes the following branches on the central repository:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs.

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

Two workflow's are described here, a basic workflow for small apps or where bug-fixes are infrequent, and an advanced workflow for larger apps or more frequent bug-fixes.

=== Basic Bug Fix Workflow ===

To make bug fixes on the 2.0 release you could simply checkout a local copy of the origin/release/2.0 branch and make you bug fixes there:

git branch --track bug-fix-2.0 origin/release/2.0
git checkout bug-fix-2.0
<make changes, build, test>
git commit -a
git push origin bug-fix-2.0:release/2.0
git branch --track bug-fix-master origin/master
git checkout bug-fix-master
git cherry-pick -x -e <sha5 of stable commit>
<build, test>
git push origin bug-fix-master:master

=== Advanced Bug Fix Workflow ===

the basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

This workflow uses the [[http://techbase.kde.org/Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for stable and unstable branches. This depends on you setting different up KDE Environments for the separate builds.

Development/Git/Feature Branch Workflow

2011-06-12T18:30:19Z

Odysseus: /* Local Feature Development */

THIS IS A DRAFT, DO NOT USE!

= Feature Branch Workflow =

This Git Workflow is the recommended KDE Git Workflow for smaller projects where new features are developed in local and/or remote feature branches before being reviewed and merged back into the master branch.

This workflow is designed to be used after initial use of the [[Development/Git/Simple_Workflow|Simple Workflow]]. It is assumed you have read and mastered the basic concepts as outlined in that Workflow, such as unstaged and staged changes, committing, rebasing and pushing.

Note that each module may choose to adopt a more complex workflow, in particular the Integration Branch Workflow, and you should check with your modules maintainers if this is the case.

More detailed information can be found on the main [[Development/Git|KDE Git page]]. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

See the [[Development/Git/Simple_Workflow#Set-up|Simple Workflow Set-up]] section for instructions on configuring Git and Cloning your Repository

== Local Feature Development ==

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

=== Create a Local Work Branch ===

To see what local branches you have:

git branch

This will initially appear as follows, with the * indicating your current working branch:

* master

To see all local and remote branches:

git branch -a

This will initially look something like:

* master
remotes/origin/HEAD -> origin/master
remotes/origin/KDE/4.5
remotes/origin/KDE/4.6
remotes/origin/kdecore/klocale-win
remotes/origin/kdeui/kdatetimeedit

To create a new local branch:

git branch <new-branch>

Now running <tt>git branch</tt> will show:

* master
my-new-branch

To change to the new branch to work on it:

git checkout <new-branch>

Now running <tt>git branch</tt> will show:

master
* my-new-branch

This sequence will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' a remote branch and is recommended for most work branches:

git branch --track <local-branch> <remote-branch>

For example to develop a new feature called 'bar' based on the central repository master branch:

git branch --track new-bar-feature origin/master

=== Commit Your Changes ===

=== Push Your Changes ===

== Local Feature Development ==

This example workflow is for locally working on new features in unstable branch and pushing them to the central repository.

This workflow is only recommended for small features or where you are the only developer on a project.

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, kdelibs includes the following branches on the central repository:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs.

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

Two workflow's are described here, a basic workflow for small apps or where bug-fixes are infrequent, and an advanced workflow for larger apps or more frequent bug-fixes.

=== Basic Bug Fix Workflow ===

To make bug fixes on the 2.0 release you could simply checkout a local copy of the origin/release/2.0 branch and make you bug fixes there:

git branch --track bug-fix-2.0 origin/release/2.0
git checkout bug-fix-2.0
<make changes, build, test>
git commit -a
git push origin bug-fix-2.0:release/2.0
git branch --track bug-fix-master origin/master
git checkout bug-fix-master
git cherry-pick -x -e <sha5 of stable commit>
<build, test>
git push origin bug-fix-master:master

=== Advanced Bug Fix Workflow ===

the basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

This workflow uses the [[http://techbase.kde.org/Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for stable and unstable branches. This depends on you setting different up KDE Environments for the separate builds.

Development/Git/Feature Branch Workflow

2011-06-12T17:38:32Z

Odysseus: /* Feature Branch Workflow */

THIS IS A DRAFT, DO NOT USE!

= Feature Branch Workflow =

This Git Workflow is the recommended KDE Git Workflow for smaller projects where new features are developed in local and/or remote feature branches before being reviewed and merged back into the master branch.

This workflow is designed to be used after initial use of the [[Development/Git/Simple_Workflow|Simple Workflow]]. It is assumed you have read and mastered the basic concepts as outlined in that Workflow, such as unstaged and staged changes, committing, rebasing and pushing.

Note that each module may choose to adopt a more complex workflow, in particular the Integration Branch Workflow, and you should check with your modules maintainers if this is the case.

More detailed information can be found on the main [[Development/Git|KDE Git page]]. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

See the [[Development/Git/Simple_Workflow#Set-up|Simple Workflow Set-up]] section for instructions on configuring Git and Cloning your Repository

== Local Feature Development ==

=== Create a Work Branch ===

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

To see what local branches you have:

git branch

To see all local and remote branches:

git branch -a

To create a new local branch:

git branch <new-branch>

To change to the new branch to work on it:

git checkout <new-branch>

This will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' and is recommended for most branches:

git branch --track <local-branch> <remote-branch>

For example to develop a new feature called 'bar' based on the master branch:

git branch --track new-bar-feature origin/master

=== Commit Your Changes ===

=== Push Your Changes ===

== Local Feature Development ==

This example workflow is for locally working on new features in unstable branch and pushing them to the central repository.

This workflow is only recommended for small features or where you are the only developer on a project.

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, kdelibs includes the following branches on the central repository:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs.

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

Two workflow's are described here, a basic workflow for small apps or where bug-fixes are infrequent, and an advanced workflow for larger apps or more frequent bug-fixes.

=== Basic Bug Fix Workflow ===

To make bug fixes on the 2.0 release you could simply checkout a local copy of the origin/release/2.0 branch and make you bug fixes there:

git branch --track bug-fix-2.0 origin/release/2.0
git checkout bug-fix-2.0
<make changes, build, test>
git commit -a
git push origin bug-fix-2.0:release/2.0
git branch --track bug-fix-master origin/master
git checkout bug-fix-master
git cherry-pick -x -e <sha5 of stable commit>
<build, test>
git push origin bug-fix-master:master

=== Advanced Bug Fix Workflow ===

the basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

This workflow uses the [[http://techbase.kde.org/Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for stable and unstable branches. This depends on you setting different up KDE Environments for the separate builds.

Development/Git/Feature Branch Workflow

2011-06-12T17:34:53Z

Odysseus: /* Feature Branch Workflow */

THIS IS A DRAFT, DO NOT USE!

= Feature Branch Workflow =

This Git Workflow is the recommended KDE Git Workflow for smaller projects where new features are developed in local and/or remote feature branches before being reviewed and merged back into the master branch.

This workflow is designed to be used after initial use of the [[Development/Git/Simple_Workflow|Simple Workflow]]. It is assumed you have read and mastered the basic concepts as outlined in that Workflow, such as staged and unstaged changes, committing, rebasing and pushing.

Note that each module may choose to adopt a more complex workflow, in particular the Integration Branch Workflow, and you should check with your modules maintainers if this is the case.

More detailed information can be found on the main [[Development/Git|KDE Git page]]. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

See the [[Development/Git/Simple_Workflow#Set-up|Simple Workflow Set-up]] section for instructions on configuring Git and Cloning your Repository

== Local Feature Development ==

=== Create a Work Branch ===

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

To see what local branches you have:

git branch

To see all local and remote branches:

git branch -a

To create a new local branch:

git branch <new-branch>

To change to the new branch to work on it:

git checkout <new-branch>

This will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' and is recommended for most branches:

git branch --track <local-branch> <remote-branch>

For example to develop a new feature called 'bar' based on the master branch:

git branch --track new-bar-feature origin/master

=== Commit Your Changes ===

=== Push Your Changes ===

== Local Feature Development ==

This example workflow is for locally working on new features in unstable branch and pushing them to the central repository.

This workflow is only recommended for small features or where you are the only developer on a project.

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, kdelibs includes the following branches on the central repository:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs.

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

Two workflow's are described here, a basic workflow for small apps or where bug-fixes are infrequent, and an advanced workflow for larger apps or more frequent bug-fixes.

=== Basic Bug Fix Workflow ===

To make bug fixes on the 2.0 release you could simply checkout a local copy of the origin/release/2.0 branch and make you bug fixes there:

git branch --track bug-fix-2.0 origin/release/2.0
git checkout bug-fix-2.0
<make changes, build, test>
git commit -a
git push origin bug-fix-2.0:release/2.0
git branch --track bug-fix-master origin/master
git checkout bug-fix-master
git cherry-pick -x -e <sha5 of stable commit>
<build, test>
git push origin bug-fix-master:master

=== Advanced Bug Fix Workflow ===

the basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

This workflow uses the [[http://techbase.kde.org/Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for stable and unstable branches. This depends on you setting different up KDE Environments for the separate builds.

Development/Git/Feature Branch Workflow

2011-06-12T17:06:42Z

Odysseus: /* Set-up */

THIS IS A DRAFT, DO NOT USE!

= Feature Branch Workflow =

This Git Workflow is the recommended KDE Git Workflow for smaller projects where new features are developed in local and/or remote feature branches before being reviewed and merged back into the master branch.

This workflow is designed to be used after initial use of the [[Development/Git/Simple_Workflow|Simple Workflow]]. It is assumed you have read and mastered the basic concepts as outlined in that Workflow, such as staged and unstaged changes.

Note that each module may choose to adopt a more complex workflow, in particular the Integration Branch Workflow, and you should check with your modules maintainers if this is the case.

More detailed information can be found on the main [[Development/Git|KDE Git page]]. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

See the [[Development/Git/Simple_Workflow#Set-up|Simple Workflow Set-up]] section for instructions on configuring Git and Cloning your Repository

== Local Feature Development ==

=== Create a Work Branch ===

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

To see what local branches you have:

git branch

To see all local and remote branches:

git branch -a

To create a new local branch:

git branch <new-branch>

To change to the new branch to work on it:

git checkout <new-branch>

This will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' and is recommended for most branches:

git branch --track <local-branch> <remote-branch>

For example to develop a new feature called 'bar' based on the master branch:

git branch --track new-bar-feature origin/master

=== Commit Your Changes ===

=== Push Your Changes ===

== Local Feature Development ==

This example workflow is for locally working on new features in unstable branch and pushing them to the central repository.

This workflow is only recommended for small features or where you are the only developer on a project.

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, kdelibs includes the following branches on the central repository:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs.

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

Two workflow's are described here, a basic workflow for small apps or where bug-fixes are infrequent, and an advanced workflow for larger apps or more frequent bug-fixes.

=== Basic Bug Fix Workflow ===

To make bug fixes on the 2.0 release you could simply checkout a local copy of the origin/release/2.0 branch and make you bug fixes there:

git branch --track bug-fix-2.0 origin/release/2.0
git checkout bug-fix-2.0
<make changes, build, test>
git commit -a
git push origin bug-fix-2.0:release/2.0
git branch --track bug-fix-master origin/master
git checkout bug-fix-master
git cherry-pick -x -e <sha5 of stable commit>
<build, test>
git push origin bug-fix-master:master

=== Advanced Bug Fix Workflow ===

the basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

This workflow uses the [[http://techbase.kde.org/Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for stable and unstable branches. This depends on you setting different up KDE Environments for the separate builds.

Development/Git/Feature Branch Workflow

2011-06-12T16:37:27Z

Odysseus: /* Simple Feature Branch Workflow */

THIS IS A DRAFT, DO NOT USE!

= Feature Branch Workflow =

This Git Workflow is the recommended KDE Git Workflow for smaller projects where new features are developed in local and/or remote feature branches before being reviewed and merged back into the master branch.

This workflow is designed to be used after initial use of the [[Development/Git/Simple_Workflow|Simple Workflow]]. It is assumed you have read and mastered the basic concepts as outlined in that Workflow, such as staged and unstaged changes.

Note that each module may choose to adopt a more complex workflow, in particular the Integration Branch Workflow, and you should check with your modules maintainers if this is the case.

More detailed information can be found on the main [[Development/Git|KDE Git page]]. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

See the [[Development/Git/Simple_Workflow#Set-up|Simple Workflow Set-up]] section for instructions on configuring Git and Cloning you Repository

== Local Feature Development ==

=== Create a Work Branch ===

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

To see what local branches you have:

git branch

To see all local and remote branches:

git branch -a

To create a new local branch:

git branch <new-branch>

To change to the new branch to work on it:

git checkout <new-branch>

This will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' and is recommended for most branches:

git branch --track <local-branch> <remote-branch>

For example to develop a new feature called 'bar' based on the master branch:

git branch --track new-bar-feature origin/master

=== Commit Your Changes ===

=== Push Your Changes ===

== Local Feature Development ==

This example workflow is for locally working on new features in unstable branch and pushing them to the central repository.

This workflow is only recommended for small features or where you are the only developer on a project.

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, kdelibs includes the following branches on the central repository:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs.

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

Two workflow's are described here, a basic workflow for small apps or where bug-fixes are infrequent, and an advanced workflow for larger apps or more frequent bug-fixes.

=== Basic Bug Fix Workflow ===

To make bug fixes on the 2.0 release you could simply checkout a local copy of the origin/release/2.0 branch and make you bug fixes there:

git branch --track bug-fix-2.0 origin/release/2.0
git checkout bug-fix-2.0
<make changes, build, test>
git commit -a
git push origin bug-fix-2.0:release/2.0
git branch --track bug-fix-master origin/master
git checkout bug-fix-master
git cherry-pick -x -e <sha5 of stable commit>
<build, test>
git push origin bug-fix-master:master

=== Advanced Bug Fix Workflow ===

the basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

This workflow uses the [[http://techbase.kde.org/Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for stable and unstable branches. This depends on you setting different up KDE Environments for the separate builds.

Development/Git/Simple Workflow

2011-06-12T16:37:24Z

Odysseus: /* Simple Workflow */

DANGER WILL ROBINSON!!! THIS IS AN INCOMPLETE DRAFT!!!

= Simple Workflow =

This workflow is designed to be as close as possible to the KDE SVN Workflow. It is only recommended to be used for the first week or two of using Git with KDE while you become familiar with the basic Git commands. Once comfortable with the basic commands you should then move on to the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

In particular this workflow will not use git branches, merging or any remote features, all feature development work will be in the local master branch (the Git name for trunk).

More detailed information can be found on the main [[Development/Git|KDE Git page]], in particular the [[Development/Git#Git_for_SVN_Users|Git for Subversion Users]] section. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow all the instructions on the [[Development/Git/Configuration|KDE Git Configuration]] page, the instructions given below assume you are using the standard configuration.

=== Clone your repository ===

You need to copy your central code repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>
cd <project>

For example to clone kdelibs:

git clone kde:kdelibs
cd kdelibs

See the [[Getting_Started/Build/Environment#Source_Path|KDE Build Environment]] page for advice on structuring your source directory.

If you have a slow or intermittent internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the [https://projects.kde.org/projects projects.kde.org] Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Local Feature Development ==

This section documents the basic workflow for developing a new feature for the master unstable branch (aka trunk in subversion). You will first make local code changes and commit them in your local repository before pushing them to the central code repository.

=== Making Local Changes and Commits ===

Changing and building code itself is no different from when using subversion, but how changed files are managed and committed is very different, as are the names and commands used. There are two key differences:
* Locally modified files can have different states that determine whether they get committed or not.
* Committing code is only local, it does not push your changes to the central repository which requires an extra step.

Files in a git repository can be in various states:
* Untracked: Files in your local repository directory that Git is not tracking changes to and are not in the central repository.
* Tracked: Files that git tracks changes to.
* Unstaged: Tracked files that have had modifications to them but have not yet been staged or committed.
* Staged: Tracked files that have had modifications made to them and have been marked to be included in the next commit
* Committed: Files that git is tracking and that have been included in a local commit that may or may not be included in the central repository.

Note that different versions of a file can be in the Untracked and Tracked states at the same time.

This difference between staged and unstaged changes allows you to choose what changes you want in each commit.

To see what the current status of your local repository is:

git status

This will show you the status as follows;

# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: src/kstagedfile.h
#
# Changed but not updated:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: src/kchangedfile.h
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# src/kuntrackedfile.txt

To add a changed file to the staging area, or to add a new file to be tracked by the repository:

git add <filename>

To delete a file from the repository and add the deletion to the staging area:

git rm <filename>

To reset a staged file to be unstaged but without losing your changes:

git reset HEAD <filename>

To reset an unstaged file to the currently committed version and irretrievably throw away your changes:

git checkout <filename>

The git commit command differs from the svn commit command in only creating a commit in your local clone of the repository, it does not merge the changes into the central repository. This allows you to queue up a series of small changes before merging them into the central repository. This local commit history can [[Development/Git/Recipes#Interactive_Rebasing|also be modified]] before you finally do push the changes.

The git commit command adds all files in the staged state into a new commit:

git commit

If you have only changed tracked files then you can automatically add all tracked files that have been changed into staging and commit all the staged files in one command:

git commit -a

=== Seeing What You Changed ===

To see a list of what files have been changed but not yet committed:

git status

To see what code changes have been made but not yet staged:

git diff
git diff <filename>

To see what code changes have been staged but not committed:

git diff --staged
git diff --staged <filename>

To see all the commits made:

git log

To see what changes were made in a commit:

git show <sha5>

The Git diff, log and show commands have many options for changing what is shown. In particular diff can show the difference in a file between any two commits.

=== Pushing Your Changes To The Central Repository ===

When you are ready to push all your local commits to the central repository, you first need to update to the latest version of the master code in the central repository:

git pull --rebase

This will update the underlying master code and apply your commits on the top of the latest version of the central repository, this is known as a rebase. Normally the rebase should apply cleanly, but sometimes there will be a conflict which you will need to resolve before you can complete applying your commits. There will be instructions given by git on how to complete the commit if required [TODO: get a copy of the output text].

Note that you cannot rebase if you have uncommitted changes. If you need to rebase but have changes that you don't want to commit, then you will need to [[Development/Git/Recipes#Stashing_Changes|stash the changes]].

Depending on how much the underlying master code has changed you may want to rebuild and test the code before doing a final rebase. It is recommended to do regular rebase's between commits to keep the possibility of conflicts to a minimum.

Once your local commits have been cleanly reapplied you can push your changes to the central repository:

git push origin master:master

Git will report if the push was successful or explain why it failed.

== Local Bug Fixing ==

If your bug fix is only for unstable master then no special actions are required, just follow the same steps as the feature development workflow above.

If your bug fix is for a stable branch then this cannot be done without using git branches. The steps required will be given below but not explained in any detail. If possible it is recommended you wait until you are familiar with using the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

The steps detailed below are very inefficient as they use the same build tree and environment for unstable and stable which may cause a lot of rebuilding. A more efficient method is detailed in the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

First, find out the name of the stable branch you want to bug fix:

git branch -r

This will list all the branches on the central repository, for example kdelibs includes the following branches:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs which we will use for this example.

Next, create a local branch pointing to the stable release branch you want to bug fix:

git branch --track KDE/4.6 origin/KDE/4.6
git checkout KDE/4.6

If you have previously created the stable branch and want to do a new bug fix, then simply check it out again and update it:

git checkout KDE/4.6
git pull --rebase

Now make your required changes to the code, build and test. Once done commit the code changes to your local repository, remembering to include the BUG: and FIXED-IN: keywords in the commit message:

git commit -a

Make a note of the sha5 of the commit as you will need it later to copy the commit to the unstable master branch.

Now you can push your changes into the central code repository:

git pull --rebase
git push origin KDE/4.6:KDE/4.6

The next step is to apply the bug fix to the unstable master branch. First check the master branch back out and update it:

git checkout master
git pull --rebase

Next, Git makes it easy to apply the existing bug fix from the stable branch by using the cherry-pick command:

git cherry-pick -x -e <sha5 of stable commit>

This will allow you to edit the commit message as required before the change is committed. If the patch does not apply cleanly a message will appear and the changes will not be committed. You will then have to edit the changes and finish the commit manually.

Once cleanly applied and committed you can build and test the change, then merge them into the central code repository:

git pull --rebase
git push origin master:master

Development/Git/Simple Workflow

2011-06-12T15:01:35Z

Odysseus: /* Simple Workflow */

DANGER WILL ROBINSON!!! THIS IS AN INCOMPLETE DRAFT!!!

= Simple Workflow =

This workflow is designed to be as close as possible to the KDE SVN Workflow. It is only recommended to be used for the first week or two of using Git with KDE while you become familiar with the basic Git commands. Once comfortable with the basic commands you should then move on to the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

In particular this workflow will not use git branches, merging or any remote features, all feature development work will be in the local master branch (the Git name for trunk).

More detailed information can be found on the main [[Development/Git|KDE Git page]], in particular the [[Development/Git#Git_for_SVN_Users|Git for Subversion Users]] section. More details on the various commands can be found on the [[Development/Git/Recipes|KDE Git Recipes]] page.

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow all the instructions on the [[Development/Git/Configuration|KDE Git Configuration]] page, the instructions given below assume you are using the standard configuration.

=== Clone your repository ===

You need to copy your central code repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>
cd <project>

In our KFoo example:

git clone kde:kfoo
cd kfoo

See the [[Getting_Started/Build/Environment#Source_Path|KDE Build Environment]] page for advice on structuring your source directory.

If you have a slow or intermittent internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the [https://projects.kde.org/projects projects.kde.org] Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Local Feature Development ==

This section documents the basic workflow for developing a new feature for the master unstable branch (aka trunk in subversion). You will first make local code changes and commit them in your local repository before pushing them to the central code repository.

=== Making Local Changes and Commits ===

Changing and building code itself is no different from when using subversion, but how changed files are managed and committed is very different, as are the names and commands used. There are two key differences:
* Locally modified files can have different states that determine whether they get committed or not.
* Committing code is only local, it does not push your changes to the central repository which requires an extra step.

Files in a git repository can be in various states:
* Untracked: Files in your local repository directory that Git is not tracking changes to and are not in the central repository.
* Tracked: Files that git tracks changes to.
* Unstaged: Tracked files that have had modifications to them but have not yet been staged or committed.
* Staged: Tracked files that have had modifications made to them and have been marked to be included in the next commit
* Committed: Files that git is tracking and that have been included in a local commit that may or may not be included in the central repository.

Note that different versions of a file can be in the Untracked and Tracked states at the same time.

This difference between staged and unstaged changes allows you to choose what changes you want in each commit.

To see what the current status of your local repository is:

git status

This will show you the status as follows;

# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: src/kstagedfile.h
#
# Changed but not updated:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: src/kchangedfile.h
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# src/kuntrackedfile.txt

To add a changed file to the staging area, or to add a new file to be tracked by the repository:

git add <filename>

To delete a file from the repository and add the deletion to the staging area:

git rm <filename>

To reset a staged file to be unstaged but without losing your changes:

git reset HEAD <filename>

To reset an unstaged file to the currently committed version and irretrievably throw away your changes:

git checkout <filename>

The git commit command differs from the svn commit command in only creating a commit in your local clone of the repository, it does not merge the changes into the central repository. This allows you to queue up a series of small changes before merging them into the central repository. This local commit history can [[Development/Git/Recipes#Interactive_Rebasing|also be modified]] before you finally do push the changes.

The git commit command adds all files in the staged state into a new commit:

git commit

If you have only changed tracked files then you can automatically add all tracked files that have been changed into staging and commit all the staged files in one command:

git commit -a

=== Seeing What You Changed ===

To see a list of what files have been changed but not yet committed:

git status

To see what code changes have been made but not yet staged:

git diff
git diff <filename>

To see what code changes have been staged but not committed:

git diff --staged
git diff --staged <filename>

To see all the commits made:

git log

To see what changes were made in a commit:

git show <sha5>

The Git diff, log and show commands have many options for changing what is shown. In particular diff can show the difference in a file between any two commits.

=== Pushing Your Changes To The Central Repository ===

When you are ready to push all your local commits to the central repository, you first need to update to the latest version of the master code in the central repository:

git pull --rebase

This will update the underlying master code and apply your commits on the top of the latest version of the central repository, this is known as a rebase. Normally the rebase should apply cleanly, but sometimes there will be a conflict which you will need to resolve before you can complete applying your commits. There will be instructions given by git on how to complete the commit if required [TODO: get a copy of the output text].

Note that you cannot rebase if you have uncommitted changes. If you need to rebase but have changes that you don't want to commit, then you will need to [[Development/Git/Recipes#Stashing_Changes|stash the changes]].

Depending on how much the underlying master code has changed you may want to rebuild and test the code before doing a final rebase. It is recommended to do regular rebase's between commits to keep the possibility of conflicts to a minimum.

Once your local commits have been cleanly reapplied you can push your changes to the central repository:

git push origin master:master

Git will report if the push was successful or explain why it failed.

== Local Bug Fixing ==

If your bug fix is only for unstable master then no special actions are required, just follow the same steps as the feature development workflow above.

If your bug fix is for a stable branch then this cannot be done without using git branches. The steps required will be given below but not explained in any detail. If possible it is recommended you wait until you are familiar with using the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

The steps detailed below are very inefficient as they use the same build tree and environment for unstable and stable which may cause a lot of rebuilding. A more efficient method is detailed in the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

First, find out the name of the stable branch you want to bug fix:

git branch -r

This will list all the branches on the central repository, for example kdelibs includes the following branches:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs which we will use for this example.

Next, create a local branch pointing to the stable release branch you want to bug fix:

git branch --track KDE/4.6 origin/KDE/4.6
git checkout KDE/4.6

If you have previously created the stable branch and want to do a new bug fix, then simply check it out again and update it:

git checkout KDE/4.6
git pull --rebase

Now make your required changes to the code, build and test. Once done commit the code changes to your local repository, remembering to include the BUG: and FIXED-IN: keywords in the commit message:

git commit -a

Make a note of the sha5 of the commit as you will need it later to copy the commit to the unstable master branch.

Now you can push your changes into the central code repository:

git pull --rebase
git push origin KDE/4.6:KDE/4.6

The next step is to apply the bug fix to the unstable master branch. First check the master branch back out and update it:

git checkout master
git pull --rebase

Next, Git makes it easy to apply the existing bug fix from the stable branch by using the cherry-pick command:

git cherry-pick -x -e <sha5 of stable commit>

This will allow you to edit the commit message as required before the change is committed. If the patch does not apply cleanly a message will appear and the changes will not be committed. You will then have to edit the changes and finish the commit manually.

Once cleanly applied and committed you can build and test the change, then merge them into the central code repository:

git pull --rebase
git push origin master:master

Development/Git/Simple Workflow

2011-06-12T14:58:16Z

Odysseus: /* Local Bug Fixing */

DANGER WILL ROBINSON!!! THIS IS AN INCOMPLETE DRAFT!!!

= Simple Workflow =

This workflow is designed to be as close as possible to the KDE SVN Workflow. It is only recommended to be used for the first week or two of using Git with KDE while you become familiar with the basic Git commands. Once comfortable with the basic commands you should then move on to the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

In particular this workflow will not use git branches or any remote features, all feature work will be in the local master (the Git name for trunk).

The worked examples given will be for an imaginary app called KFoo in a git.kde.org code repository called 'kfoo'.

More detailed information can be found on the main [[Development/Git|KDE Git page]].

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow all the instructions on the [[Development/Git/Configuration|KDE Git Configuration]] page, the instructions given below assume you are using the standard configuration.

=== Clone your repository ===

You need to copy your central code repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>
cd <project>

In our KFoo example:

git clone kde:kfoo
cd kfoo

See the [[Getting_Started/Build/Environment#Source_Path|KDE Build Environment]] page for advice on structuring your source directory.

If you have a slow or intermittent internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the [https://projects.kde.org/projects projects.kde.org] Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Local Feature Development ==

This section documents the basic workflow for developing a new feature for the master unstable branch (aka trunk in subversion). You will first make local code changes and commit them in your local repository before pushing them to the central code repository.

=== Making Local Changes and Commits ===

Changing and building code itself is no different from when using subversion, but how changed files are managed and committed is very different, as are the names and commands used. There are two key differences:
* Locally modified files can have different states that determine whether they get committed or not.
* Committing code is only local, it does not push your changes to the central repository which requires an extra step.

Files in a git repository can be in various states:
* Untracked: Files in your local repository directory that Git is not tracking changes to and are not in the central repository.
* Tracked: Files that git tracks changes to.
* Unstaged: Tracked files that have had modifications to them but have not yet been staged or committed.
* Staged: Tracked files that have had modifications made to them and have been marked to be included in the next commit
* Committed: Files that git is tracking and that have been included in a local commit that may or may not be included in the central repository.

Note that different versions of a file can be in the Untracked and Tracked states at the same time.

This difference between staged and unstaged changes allows you to choose what changes you want in each commit.

To see what the current status of your local repository is:

git status

This will show you the status as follows;

# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: src/kstagedfile.h
#
# Changed but not updated:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: src/kchangedfile.h
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# src/kuntrackedfile.txt

To add a changed file to the staging area, or to add a new file to be tracked by the repository:

git add <filename>

To delete a file from the repository and add the deletion to the staging area:

git rm <filename>

To reset a staged file to be unstaged but without losing your changes:

git reset HEAD <filename>

To reset an unstaged file to the currently committed version and irretrievably throw away your changes:

git checkout <filename>

The git commit command differs from the svn commit command in only creating a commit in your local clone of the repository, it does not merge the changes into the central repository. This allows you to queue up a series of small changes before merging them into the central repository. This local commit history can [[Development/Git/Recipes#Interactive_Rebasing|also be modified]] before you finally do push the changes.

The git commit command adds all files in the staged state into a new commit:

git commit

If you have only changed tracked files then you can automatically add all tracked files that have been changed into staging and commit all the staged files in one command:

git commit -a

=== Seeing What You Changed ===

To see a list of what files have been changed but not yet committed:

git status

To see what code changes have been made but not yet staged:

git diff
git diff <filename>

To see what code changes have been staged but not committed:

git diff --staged
git diff --staged <filename>

To see all the commits made:

git log

To see what changes were made in a commit:

git show <sha5>

The Git diff, log and show commands have many options for changing what is shown. In particular diff can show the difference in a file between any two commits.

=== Pushing Your Changes To The Central Repository ===

When you are ready to push all your local commits to the central repository, you first need to update to the latest version of the master code in the central repository:

git pull --rebase

This will update the underlying master code and apply your commits on the top of the latest version of the central repository, this is known as a rebase. Normally the rebase should apply cleanly, but sometimes there will be a conflict which you will need to resolve before you can complete applying your commits. There will be instructions given by git on how to complete the commit if required [TODO: get a copy of the output text].

Note that you cannot rebase if you have uncommitted changes. If you need to rebase but have changes that you don't want to commit, then you will need to [[Development/Git/Recipes#Stashing_Changes|stash the changes]].

Depending on how much the underlying master code has changed you may want to rebuild and test the code before doing a final rebase. It is recommended to do regular rebase's between commits to keep the possibility of conflicts to a minimum.

Once your local commits have been cleanly reapplied you can push your changes to the central repository:

git push origin master:master

Git will report if the push was successful or explain why it failed.

== Local Bug Fixing ==

If your bug fix is only for unstable master then no special actions are required, just follow the same steps as the feature development workflow above.

If your bug fix is for a stable branch then this cannot be done without using git branches. The steps required will be given below but not explained in any detail. If possible it is recommended you wait until you are familiar with using the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

The steps detailed below are very inefficient as they use the same build tree and environment for unstable and stable which may cause a lot of rebuilding. A more efficient method is detailed in the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

First, find out the name of the stable branch you want to bug fix:

git branch -r

This will list all the branches on the central repository, for example kdelibs includes the following branches:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs which we will use for this example.

Next, create a local branch pointing to the stable release branch you want to bug fix:

git branch --track KDE/4.6 origin/KDE/4.6
git checkout KDE/4.6

If you have previously created the stable branch and want to do a new bug fix, then simply check it out again and update it:

git checkout KDE/4.6
git pull --rebase

Now make your required changes to the code, build and test. Once done commit the code changes to your local repository, remembering to include the BUG: and FIXED-IN: keywords in the commit message:

git commit -a

Make a note of the sha5 of the commit as you will need it later to copy the commit to the unstable master branch.

Now you can push your changes into the central code repository:

git pull --rebase
git push origin KDE/4.6:KDE/4.6

The next step is to apply the bug fix to the unstable master branch. First check the master branch back out and update it:

git checkout master
git pull --rebase

Next, Git makes it easy to apply the existing bug fix from the stable branch by using the cherry-pick command:

git cherry-pick -x -e <sha5 of stable commit>

This will allow you to edit the commit message as required before the change is committed. If the patch does not apply cleanly a message will appear and the changes will not be committed. You will then have to edit the changes and finish the commit manually.

Once cleanly applied and committed you can build and test the change, then merge them into the central code repository:

git pull --rebase
git push origin master:master

Development/Git/Simple Workflow

2011-06-12T14:53:26Z

Odysseus: /* Local Feature Development */

DANGER WILL ROBINSON!!! THIS IS AN INCOMPLETE DRAFT!!!

= Simple Workflow =

This workflow is designed to be as close as possible to the KDE SVN Workflow. It is only recommended to be used for the first week or two of using Git with KDE while you become familiar with the basic Git commands. Once comfortable with the basic commands you should then move on to the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

In particular this workflow will not use git branches or any remote features, all feature work will be in the local master (the Git name for trunk).

The worked examples given will be for an imaginary app called KFoo in a git.kde.org code repository called 'kfoo'.

More detailed information can be found on the main [[Development/Git|KDE Git page]].

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow all the instructions on the [[Development/Git/Configuration|KDE Git Configuration]] page, the instructions given below assume you are using the standard configuration.

=== Clone your repository ===

You need to copy your central code repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>
cd <project>

In our KFoo example:

git clone kde:kfoo
cd kfoo

See the [[Getting_Started/Build/Environment#Source_Path|KDE Build Environment]] page for advice on structuring your source directory.

If you have a slow or intermittent internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the [https://projects.kde.org/projects projects.kde.org] Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Local Feature Development ==

This section documents the basic workflow for developing a new feature for the master unstable branch (aka trunk in subversion). You will first make local code changes and commit them in your local repository before pushing them to the central code repository.

=== Making Local Changes and Commits ===

Changing and building code itself is no different from when using subversion, but how changed files are managed and committed is very different, as are the names and commands used. There are two key differences:
* Locally modified files can have different states that determine whether they get committed or not.
* Committing code is only local, it does not push your changes to the central repository which requires an extra step.

Files in a git repository can be in various states:
* Untracked: Files in your local repository directory that Git is not tracking changes to and are not in the central repository.
* Tracked: Files that git tracks changes to.
* Unstaged: Tracked files that have had modifications to them but have not yet been staged or committed.
* Staged: Tracked files that have had modifications made to them and have been marked to be included in the next commit
* Committed: Files that git is tracking and that have been included in a local commit that may or may not be included in the central repository.

Note that different versions of a file can be in the Untracked and Tracked states at the same time.

This difference between staged and unstaged changes allows you to choose what changes you want in each commit.

To see what the current status of your local repository is:

git status

This will show you the status as follows;

# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: src/kstagedfile.h
#
# Changed but not updated:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: src/kchangedfile.h
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# src/kuntrackedfile.txt

To add a changed file to the staging area, or to add a new file to be tracked by the repository:

git add <filename>

To delete a file from the repository and add the deletion to the staging area:

git rm <filename>

To reset a staged file to be unstaged but without losing your changes:

git reset HEAD <filename>

To reset an unstaged file to the currently committed version and irretrievably throw away your changes:

git checkout <filename>

The git commit command differs from the svn commit command in only creating a commit in your local clone of the repository, it does not merge the changes into the central repository. This allows you to queue up a series of small changes before merging them into the central repository. This local commit history can [[Development/Git/Recipes#Interactive_Rebasing|also be modified]] before you finally do push the changes.

The git commit command adds all files in the staged state into a new commit:

git commit

If you have only changed tracked files then you can automatically add all tracked files that have been changed into staging and commit all the staged files in one command:

git commit -a

=== Seeing What You Changed ===

To see a list of what files have been changed but not yet committed:

git status

To see what code changes have been made but not yet staged:

git diff
git diff <filename>

To see what code changes have been staged but not committed:

git diff --staged
git diff --staged <filename>

To see all the commits made:

git log

To see what changes were made in a commit:

git show <sha5>

The Git diff, log and show commands have many options for changing what is shown. In particular diff can show the difference in a file between any two commits.

=== Pushing Your Changes To The Central Repository ===

When you are ready to push all your local commits to the central repository, you first need to update to the latest version of the master code in the central repository:

git pull --rebase

This will update the underlying master code and apply your commits on the top of the latest version of the central repository, this is known as a rebase. Normally the rebase should apply cleanly, but sometimes there will be a conflict which you will need to resolve before you can complete applying your commits. There will be instructions given by git on how to complete the commit if required [TODO: get a copy of the output text].

Note that you cannot rebase if you have uncommitted changes. If you need to rebase but have changes that you don't want to commit, then you will need to [[Development/Git/Recipes#Stashing_Changes|stash the changes]].

Depending on how much the underlying master code has changed you may want to rebuild and test the code before doing a final rebase. It is recommended to do regular rebase's between commits to keep the possibility of conflicts to a minimum.

Once your local commits have been cleanly reapplied you can push your changes to the central repository:

git push origin master:master

Git will report if the push was successful or explain why it failed.

== Local Bug Fixing ==

If your bug fix is only for unstable master then no special actions are required, just follow the same steps as the feature development workflow above.

If your bug fix is for a stable branch then this cannot be done without using git branches. The steps required will be given below but not explained in any detail. If possible it is recommended you wait until you are familiar with using the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

The steps detailed below are very inefficient as they use the same build tree and environment for unstable and stable which may cause a lot of rebuilding. A more efficient method is detailed in the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

First, find out the name of the stable branch you want to bug fix:

git branch -r

This will list all the branches on the central repository, for example kdelibs includes the following branches:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs which we will use for this example.

Next, create a local branch pointing to the stable release branch you want to bug fix:

git branch --track KDE/4.6 origin/KDE/4.6
git checkout KDE/4.6

If you have previously created the stable branch and want to do a new bug fix, then simply check it out again and update it:

git checkout KDE/4.6
git pull --rebase

Now make your required changes to the code, build and test. Once done commit the code changes to your local repository, remembering to include the BUG: and FIXED-IN: keywords in the commit message:

git commit -a

Make a note of the sha5 of the commit as you will need it later to copy the commit to the unstable master branch.

Now you can merge your changes into the central code repository:

git pull --rebase
git push origin KDE/4.6:KDE/4.6 //TODO or use git merge???

The next step is to apply the bug fix to the unstable master branch. First check the master branch back out and update it:

git checkout master
git pull --rebase

Next, Git makes it easy to apply the existing bug fix from the stable branch by using the cherry-pick command:

git cherry-pick -x -e <sha5 of stable commit>

This will allow you to edit the commit message as required before the change is committed. If the patch does not apply cleanly a message will appear and the changes will not be committed. You will then have to edit the changes and finish the commit manually.

Once cleanly applied and committed you can build and test the change, then merge them into the central code repository:

git pull --rebase
git push origin master:master //TODO or use git merge???

Development/Git/Simple Workflow

2011-06-12T14:42:25Z

Odysseus: /* Local Feature Development */

DANGER WILL ROBINSON!!! THIS IS AN INCOMPLETE DRAFT!!!

= Simple Workflow =

This workflow is designed to be as close as possible to the KDE SVN Workflow. It is only recommended to be used for the first week or two of using Git with KDE while you become familiar with the basic Git commands. Once comfortable with the basic commands you should then move on to the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

In particular this workflow will not use git branches or any remote features, all feature work will be in the local master (the Git name for trunk).

The worked examples given will be for an imaginary app called KFoo in a git.kde.org code repository called 'kfoo'.

More detailed information can be found on the main [[Development/Git|KDE Git page]].

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow all the instructions on the [[Development/Git/Configuration|KDE Git Configuration]] page, the instructions given below assume you are using the standard configuration.

=== Clone your repository ===

You need to copy your central code repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>
cd <project>

In our KFoo example:

git clone kde:kfoo
cd kfoo

See the [[Getting_Started/Build/Environment#Source_Path|KDE Build Environment]] page for advice on structuring your source directory.

If you have a slow or intermittent internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the [https://projects.kde.org/projects projects.kde.org] Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Local Feature Development ==

This section documents the basic workflow for developing a new feature for the master unstable branch (aka trunk in subversion). You will first make local code changes and commit them in your local repository before pushing them to the central code repository.

=== Making Local Change Commits ===

Changing and building code itself is no different from when using subversion, but how changed files are managed and committed is very different, as are the names and commands used. There are two key differences:
* Locally modified files can have different states that determine whether they get committed or not.
* Committing code is only local, it does not merge your changes into the central repository which requires an extra step.

Files in a git repository can be in various states:
* Untracked: Files in your local repository directory that Git is not tracking changes to and are not in the central repository.
* Tracked: Files that git tracks changes to.
* Unstaged: Tracked files that have had modifications to them but have not yet been staged or committed.
* Staged: Tracked files that have had modifications made to them and have been marked to be included in the next commit
* Committed: Files that git is tracking and that have been included in a local commit that may or may not be included in the central repository.

Note that different versions of a file can be in the Untracked and Tracked states at the same time.

This difference between staged and unstaged changes allows you to choose what changes you want in each commit.

To see what the current status of your local repository is:

git status

This will show you the status as follows;

# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: kstagedfile.h
#
# Changed but not updated:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: kchangedfile.h
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# kuntrackedfile.txt

To add a changed file to the staging area, or to add a new file to be tracked by the repository:

git add <filename>

To delete a file from the repository and add the deletion to the staging area:

git rm <filename>

To reset a staged file to be unstaged but without losing your changes:

git reset HEAD <filename>

To reset an unstaged file to the currently committed version and irretrievably throw away your changes:

git checkout <filename>

The git commit command differs from the svn commit command in only creating a commit in your local clone of the repository, it does not merge the changes into the central repository. This allows you to queue up a series of small changes before merging them into the central repository. This local commit history can also be modified before you finally do merge the changes.

The git commit command adds all files in the staged state into a new commit:

git commit

If you have only changed tracked files then you can automatically add all tracked files that have been changed into staging and commit all the staged files in one command:

git commit -a

=== Seeing What You Changed ===

To see a list of what files have been changed but not yet committed:

git status

To see what code changes have been made but not yet staged:

git diff
git diff <filename>

To see what code changes have been staged but not committed:

git diff --staged
git diff --staged <filename>

To see all the commits made:

git log

To see what changes were made in a commit:

git show <sha5>

The Git diff, log and show commands have many options for changing what is shown. In particular diff can show the difference between any two commits.

=== Pushing Your Changes To The Central Repository ===

When you are ready to merge all your local commits into the central repository, you first need to update to the latest version of the master code in the central repository:

git pull --rebase

This will update the underlying master code and apply your commits on the top of the latest version of the central repository, this is known as a rebase. Normally the rebase should apply cleanly, but sometimes there will be a conflict which you will need to resolve before you can complete applying your commits. There will be instructions given by git on how to complete the commit if required [TODO: get a copy of the output text].

Note that you cannot rebase if you have uncommitted changes. If you need to rebase but have changes that you don't want to commit, then you will need to [[Development/Git/Recipes#Stashing_Changes|stash the changes]].

Depending on how much the underlying master code has changed you may want to rebuild and test the code before doing a final rebase. It is recommended to do regular rebase's between commits to keep the possibility of conflicts to a minimum.

Once your local commits have been cleanly reapplied you can push your changes to the central repository:

git push origin master:master

Git will report if the push was successful or explain why it failed.

== Local Bug Fixing ==

If your bug fix is only for unstable master then no special actions are required, just follow the same steps as the feature development workflow above.

If your bug fix is for a stable branch then this cannot be done without using git branches. The steps required will be given below but not explained in any detail. If possible it is recommended you wait until you are familiar with using the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

The steps detailed below are very inefficient as they use the same build tree and environment for unstable and stable which may cause a lot of rebuilding. A more efficient method is detailed in the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

First, find out the name of the stable branch you want to bug fix:

git branch -r

This will list all the branches on the central repository, for example kdelibs includes the following branches:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs which we will use for this example.

Next, create a local branch pointing to the stable release branch you want to bug fix:

git branch --track KDE/4.6 origin/KDE/4.6
git checkout KDE/4.6

If you have previously created the stable branch and want to do a new bug fix, then simply check it out again and update it:

git checkout KDE/4.6
git pull --rebase

Now make your required changes to the code, build and test. Once done commit the code changes to your local repository, remembering to include the BUG: and FIXED-IN: keywords in the commit message:

git commit -a

Make a note of the sha5 of the commit as you will need it later to copy the commit to the unstable master branch.

Now you can merge your changes into the central code repository:

git pull --rebase
git push origin KDE/4.6:KDE/4.6 //TODO or use git merge???

The next step is to apply the bug fix to the unstable master branch. First check the master branch back out and update it:

git checkout master
git pull --rebase

Next, Git makes it easy to apply the existing bug fix from the stable branch by using the cherry-pick command:

git cherry-pick -x -e <sha5 of stable commit>

This will allow you to edit the commit message as required before the change is committed. If the patch does not apply cleanly a message will appear and the changes will not be committed. You will then have to edit the changes and finish the commit manually.

Once cleanly applied and committed you can build and test the change, then merge them into the central code repository:

git pull --rebase
git push origin master:master //TODO or use git merge???

Development/Git/Simple Workflow

2011-06-12T14:11:51Z

Odysseus: /* Basic Actions */

DANGER WILL ROBINSON!!! THIS IS AN INCOMPLETE DRAFT!!!

= Simple Workflow =

This workflow is designed to be as close as possible to the KDE SVN Workflow. It is only recommended to be used for the first week or two of using Git with KDE while you become familiar with the basic Git commands. Once comfortable with the basic commands you should then move on to the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

In particular this workflow will not use git branches or any remote features, all feature work will be in the local master (the Git name for trunk).

The worked examples given will be for an imaginary app called KFoo in a git.kde.org code repository called 'kfoo'.

More detailed information can be found on the main [[Development/Git|KDE Git page]].

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow all the instructions on the [[Development/Git/Configuration|KDE Git Configuration]] page, the instructions given below assume you are using the standard configuration.

=== Clone your repository ===

You need to copy your central code repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>
cd <project>

In our KFoo example:

git clone kde:kfoo
cd kfoo

See the [[Getting_Started/Build/Environment#Source_Path|KDE Build Environment]] page for advice on structuring your source directory.

If you have a slow or intermittent internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the [https://projects.kde.org/projects projects.kde.org] Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Local Feature Development ==

This section documents the basic workflow for developing a new feature in the master unstable branch (aka trunk in subversion).

=== Making and Committing Changes ===

Changing and building code itself is no different from when using subversion, but how changed files are managed and committed is very different, as are the names and commands used. There are two key differences:
* Locally modified files can have different states that determine whether they get committed or not.
* Committing code is only local, it does not merge your changes into the central repository which requires an extra step.

Files in a git repository can be in various states:
* Untracked: Files in your local repository directory that Git is not tracking changes to and are not in the central repository.
* Tracked: Files that git tracks changes to.
* Unstaged: Tracked files that have had modifications to them but have not yet been staged or committed.
* Staged: Tracked files that have had modifications made to them and have been marked to be included in the next commit
* Committed: Files that git is tracking and that have been included in a local commit that may or may not be included in the central repository.

Note that different versions of a file can be in the Untracked and Tracked states at the same time.

This difference between staged and unstaged changes allows you to choose what changes you want in each commit.

To see what the current status of your local repository is:

git status

This will show you the status as follows;

# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: kstagedfile.h
#
# Changed but not updated:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: kchangedfile.h
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# kuntrackedfile.txt

To add a changed file to the staging area, or to add a new file to be tracked by the repository:

git add <filename>

To delete a file from the repository and add the deletion to the staging area:

git rm <filename>

To reset an unstaged or staged file to the currently committed version and irretrievably throw away you current changes:

git checkout <filename>

To reset all unstaged or staged files to the currently committed version and irretrievably throw away you current changes:

git

The git commit command differs from the svn commit command in only creating a commit in your local clone of the repository, it does not merge the changes into the central repository. This allows you to queue up a series of small changes before merging them into the central repository. This local commit history can also be modified before you finally do merge the changes.

The git commit command adds all files in the staging state into a new commit:

git commit

If you have only changed tracked files then you can automatically add all tracked files that have been changed into staging and commit all the staged files in one command:

git commit -a

=== Seeing What You Changed ===

To see a list of what files have been changed but not yet committed:

git status

To see what code changes have been made but not yet staged:

git diff
git diff <filename>

To see what code changes have been staged but not committed:

git diff --staged
git diff --staged <filename>

To see all the commits made:

git log

To see what changes were made in a commit:

git show <sha5>

The Git diff, log and show commands have many options for changing what is shown. In particular diff can show the difference between any two commits.

=== Merging Your Changes ===

When you are ready to merge all your local commits into the central repository, you first need to update to the latest version of the master code in the central repository:

git pull --rebase

This will

== Local Bug Fixing ==

If your bug fix is only for unstable master then no special actions are required, just follow the same steps as the feature development workflow above.

If your bug fix is for a stable branch then this cannot be done without using git branches. The steps required will be given below but not explained in any detail. If possible it is recommended you wait until you are familiar with using the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

The steps detailed below are very inefficient as they use the same build tree and environment for unstable and stable which may cause a lot of rebuilding. A more efficient method is detailed in the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

First, find out the name of the stable branch you want to bug fix:

git branch -r

This will list all the branches on the central repository, for example kdelibs includes the following branches:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs which we will use for this example.

Next, create a local branch pointing to the stable release branch you want to bug fix:

git branch --track KDE/4.6 origin/KDE/4.6
git checkout KDE/4.6

If you have previously created the stable branch and want to do a new bug fix, then simply check it out again and update it:

git checkout KDE/4.6
git pull --rebase

Now make your required changes to the code, build and test. Once done commit the code changes to your local repository, remembering to include the BUG: and FIXED-IN: keywords in the commit message:

git commit -a

Make a note of the sha5 of the commit as you will need it later to copy the commit to the unstable master branch.

Now you can merge your changes into the central code repository:

git pull --rebase
git push origin KDE/4.6:KDE/4.6 //TODO or use git merge???

The next step is to apply the bug fix to the unstable master branch. First check the master branch back out and update it:

git checkout master
git pull --rebase

Next, Git makes it easy to apply the existing bug fix from the stable branch by using the cherry-pick command:

git cherry-pick -x -e <sha5 of stable commit>

This will allow you to edit the commit message as required before the change is committed. If the patch does not apply cleanly a message will appear and the changes will not be committed. You will then have to edit the changes and finish the commit manually.

Once cleanly applied and committed you can build and test the change, then merge them into the central code repository:

git pull --rebase
git push origin master:master //TODO or use git merge???

Development/Git/Simple Workflow

2011-06-12T14:10:39Z

Odysseus: /* Local Feature Development */

DANGER WILL ROBINSON!!! THIS IS AN INCOMPLETE DRAFT!!!

= Simple Workflow =

This workflow is designed to be as close as possible to the KDE SVN Workflow. It is only recommended to be used for the first week or two of using Git with KDE while you become familiar with the basic Git commands. Once comfortable with the basic commands you should then move on to the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

In particular this workflow will not use git branches or any remote features, all feature work will be in the local master (the Git name for trunk).

The worked examples given will be for an imaginary app called KFoo in a git.kde.org code repository called 'kfoo'.

More detailed information can be found on the main [[Development/Git|KDE Git page]].

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow all the instructions on the [[Development/Git/Configuration|KDE Git Configuration]] page, the instructions given below assume you are using the standard configuration.

=== Clone your repository ===

You need to copy your central code repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>
cd <project>

In our KFoo example:

git clone kde:kfoo
cd kfoo

See the [[Getting_Started/Build/Environment#Source_Path|KDE Build Environment]] page for advice on structuring your source directory.

If you have a slow or intermittent internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the [https://projects.kde.org/projects projects.kde.org] Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Basic Actions ==

This section documents basic actions that are performed within your workflow.

See also the [[Development/Git/Recipes|KDE Git Recipes]] page.

=== Making and Committing Changes ===

Changing and building code itself is no different from when using subversion, but how changed files are managed and committed is very different, as are the names and commands used. There are two key differences:
* Locally modified files can have different states that determine whether they get committed or not.
* Committing code is only local, it does not merge your changes into the central repository which requires an extra step.

Files in a git repository can be in various states:
* Untracked: Files in your local repository directory that Git is not tracking changes to and are not in the central repository.
* Tracked: Files that git tracks changes to.
* Unstaged: Tracked files that have had modifications to them but have not yet been staged or committed.
* Staged: Tracked files that have had modifications made to them and have been marked to be included in the next commit
* Committed: Files that git is tracking and that have been included in a local commit that may or may not be included in the central repository.

Note that different versions of a file can be in the Untracked and Tracked states at the same time.

This difference between staged and unstaged changes allows you to choose what changes you want in each commit.

To see what the current status of your local repository is:

git status

This will show you the status as follows;

# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: kstagedfile.h
#
# Changed but not updated:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: kchangedfile.h
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# kuntrackedfile.txt

To add a changed file to the staging area, or to add a new file to be tracked by the repository:

git add <filename>

To delete a file from the repository and add the deletion to the staging area:

git rm <filename>

To reset an unstaged or staged file to the currently committed version and irretrievably throw away you current changes:

git checkout <filename>

To reset all unstaged or staged files to the currently committed version and irretrievably throw away you current changes:

git

The git commit command differs from the svn commit command in only creating a commit in your local clone of the repository, it does not merge the changes into the central repository. This allows you to queue up a series of small changes before merging them into the central repository. This local commit history can also be modified before you finally do merge the changes.

The git commit command adds all files in the staging state into a new commit:

git commit

If you have only changed tracked files then you can automatically add all tracked files that have been changed into staging and commit all the staged files in one command:

git commit -a

=== Seeing What You Changed ===

To see a list of what files have been changed but not yet committed:

git status

To see what code changes have been made but not yet staged:

git diff
git diff <filename>

To see what code changes have been staged but not committed:

git diff --staged
git diff --staged <filename>

To see all the commits made:

git log

To see what changes were made in a commit:

git show <sha5>

The Git diff, log and show commands have many options for changing what is shown. In particular diff can show the difference between any two commits.

=== Merging Your Changes ===

When you are ready to merge all your local commits into the central repository, you first need to update to the latest version of the master code in the central repository:

git pull --rebase

This will

== Local Bug Fixing ==

If your bug fix is only for unstable master then no special actions are required, just follow the same steps as the feature development workflow above.

If your bug fix is for a stable branch then this cannot be done without using git branches. The steps required will be given below but not explained in any detail. If possible it is recommended you wait until you are familiar with using the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

The steps detailed below are very inefficient as they use the same build tree and environment for unstable and stable which may cause a lot of rebuilding. A more efficient method is detailed in the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

First, find out the name of the stable branch you want to bug fix:

git branch -r

This will list all the branches on the central repository, for example kdelibs includes the following branches:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs which we will use for this example.

Next, create a local branch pointing to the stable release branch you want to bug fix:

git branch --track KDE/4.6 origin/KDE/4.6
git checkout KDE/4.6

If you have previously created the stable branch and want to do a new bug fix, then simply check it out again and update it:

git checkout KDE/4.6
git pull --rebase

Now make your required changes to the code, build and test. Once done commit the code changes to your local repository, remembering to include the BUG: and FIXED-IN: keywords in the commit message:

git commit -a

Make a note of the sha5 of the commit as you will need it later to copy the commit to the unstable master branch.

Now you can merge your changes into the central code repository:

git pull --rebase
git push origin KDE/4.6:KDE/4.6 //TODO or use git merge???

The next step is to apply the bug fix to the unstable master branch. First check the master branch back out and update it:

git checkout master
git pull --rebase

Next, Git makes it easy to apply the existing bug fix from the stable branch by using the cherry-pick command:

git cherry-pick -x -e <sha5 of stable commit>

This will allow you to edit the commit message as required before the change is committed. If the patch does not apply cleanly a message will appear and the changes will not be committed. You will then have to edit the changes and finish the commit manually.

Once cleanly applied and committed you can build and test the change, then merge them into the central code repository:

git pull --rebase
git push origin master:master //TODO or use git merge???

Development/Git/Simple Workflow

2011-06-12T14:10:24Z

Odysseus: /* Basic Actions */

DANGER WILL ROBINSON!!! THIS IS AN INCOMPLETE DRAFT!!!

= Simple Workflow =

This workflow is designed to be as close as possible to the KDE SVN Workflow. It is only recommended to be used for the first week or two of using Git with KDE while you become familiar with the basic Git commands. Once comfortable with the basic commands you should then move on to the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

In particular this workflow will not use git branches or any remote features, all feature work will be in the local master (the Git name for trunk).

The worked examples given will be for an imaginary app called KFoo in a git.kde.org code repository called 'kfoo'.

More detailed information can be found on the main [[Development/Git|KDE Git page]].

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow all the instructions on the [[Development/Git/Configuration|KDE Git Configuration]] page, the instructions given below assume you are using the standard configuration.

=== Clone your repository ===

You need to copy your central code repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>
cd <project>

In our KFoo example:

git clone kde:kfoo
cd kfoo

See the [[Getting_Started/Build/Environment#Source_Path|KDE Build Environment]] page for advice on structuring your source directory.

If you have a slow or intermittent internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the [https://projects.kde.org/projects projects.kde.org] Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Basic Actions ==

This section documents basic actions that are performed within your workflow.

See also the [[Development/Git/Recipes|KDE Git Recipes]] page.

=== Making and Committing Changes ===

Changing and building code itself is no different from when using subversion, but how changed files are managed and committed is very different, as are the names and commands used. There are two key differences:
* Locally modified files can have different states that determine whether they get committed or not.
* Committing code is only local, it does not merge your changes into the central repository which requires an extra step.

Files in a git repository can be in various states:
* Untracked: Files in your local repository directory that Git is not tracking changes to and are not in the central repository.
* Tracked: Files that git tracks changes to.
* Unstaged: Tracked files that have had modifications to them but have not yet been staged or committed.
* Staged: Tracked files that have had modifications made to them and have been marked to be included in the next commit
* Committed: Files that git is tracking and that have been included in a local commit that may or may not be included in the central repository.

Note that different versions of a file can be in the Untracked and Tracked states at the same time.

This difference between staged and unstaged changes allows you to choose what changes you want in each commit.

To see what the current status of your local repository is:

git status

This will show you the status as follows;

# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: kstagedfile.h
#
# Changed but not updated:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: kchangedfile.h
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# kuntrackedfile.txt

To add a changed file to the staging area, or to add a new file to be tracked by the repository:

git add <filename>

To delete a file from the repository and add the deletion to the staging area:

git rm <filename>

To reset an unstaged or staged file to the currently committed version and irretrievably throw away you current changes:

git checkout <filename>

To reset all unstaged or staged files to the currently committed version and irretrievably throw away you current changes:

git

The git commit command differs from the svn commit command in only creating a commit in your local clone of the repository, it does not merge the changes into the central repository. This allows you to queue up a series of small changes before merging them into the central repository. This local commit history can also be modified before you finally do merge the changes.

The git commit command adds all files in the staging state into a new commit:

git commit

If you have only changed tracked files then you can automatically add all tracked files that have been changed into staging and commit all the staged files in one command:

git commit -a

=== Seeing What You Changed ===

To see a list of what files have been changed but not yet committed:

git status

To see what code changes have been made but not yet staged:

git diff
git diff <filename>

To see what code changes have been staged but not committed:

git diff --staged
git diff --staged <filename>

To see all the commits made:

git log

To see what changes were made in a commit:

git show <sha5>

The Git diff, log and show commands have many options for changing what is shown. In particular diff can show the difference between any two commits.

=== Merging Your Changes ===

When you are ready to merge all your local commits into the central repository, you first need to update to the latest version of the master code in the central repository:

git pull --rebase

This will

== Local Feature Development ==

== Local Bug Fixing ==

If your bug fix is only for unstable master then no special actions are required, just follow the same steps as the feature development workflow above.

If your bug fix is for a stable branch then this cannot be done without using git branches. The steps required will be given below but not explained in any detail. If possible it is recommended you wait until you are familiar with using the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

The steps detailed below are very inefficient as they use the same build tree and environment for unstable and stable which may cause a lot of rebuilding. A more efficient method is detailed in the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

First, find out the name of the stable branch you want to bug fix:

git branch -r

This will list all the branches on the central repository, for example kdelibs includes the following branches:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs which we will use for this example.

Next, create a local branch pointing to the stable release branch you want to bug fix:

git branch --track KDE/4.6 origin/KDE/4.6
git checkout KDE/4.6

If you have previously created the stable branch and want to do a new bug fix, then simply check it out again and update it:

git checkout KDE/4.6
git pull --rebase

Now make your required changes to the code, build and test. Once done commit the code changes to your local repository, remembering to include the BUG: and FIXED-IN: keywords in the commit message:

git commit -a

Make a note of the sha5 of the commit as you will need it later to copy the commit to the unstable master branch.

Now you can merge your changes into the central code repository:

git pull --rebase
git push origin KDE/4.6:KDE/4.6 //TODO or use git merge???

The next step is to apply the bug fix to the unstable master branch. First check the master branch back out and update it:

git checkout master
git pull --rebase

Next, Git makes it easy to apply the existing bug fix from the stable branch by using the cherry-pick command:

git cherry-pick -x -e <sha5 of stable commit>

This will allow you to edit the commit message as required before the change is committed. If the patch does not apply cleanly a message will appear and the changes will not be committed. You will then have to edit the changes and finish the commit manually.

Once cleanly applied and committed you can build and test the change, then merge them into the central code repository:

git pull --rebase
git push origin master:master //TODO or use git merge???

Development/Git/Simple Workflow

2011-06-12T13:42:13Z

Odysseus: /* Committing Your Changes */

DANGER WILL ROBINSON!!! THIS IS AN INCOMPLETE DRAFT!!!

= Simple Workflow =

This workflow is designed to be as close as possible to the KDE SVN Workflow. It is only recommended to be used for the first week or two of using Git with KDE while you become familiar with the basic Git commands. Once comfortable with the basic commands you should then move on to the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

In particular this workflow will not use git branches or any remote features, all feature work will be in the local master (the Git name for trunk).

The worked examples given will be for an imaginary app called KFoo in a git.kde.org code repository called 'kfoo'.

More detailed information can be found on the main [[Development/Git|KDE Git page]].

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow all the instructions on the [[Development/Git/Configuration|KDE Git Configuration]] page, the instructions given below assume you are using the standard configuration.

=== Clone your repository ===

You need to copy your central code repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>
cd <project>

In our KFoo example:

git clone kde:kfoo
cd kfoo

See the [[Getting_Started/Build/Environment#Source_Path|KDE Build Environment]] page for advice on structuring your source directory.

If you have a slow or intermittent internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the [https://projects.kde.org/projects projects.kde.org] Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Basic Actions ==

This section documents basic actions that are performed within your workflow.

See also the [[Development/Git/Recipes|KDE Git Recipes]] page.

=== Making changes ===

Changing code is no different from when using subversion.

=== Committing Your Changes ===

The git commit command differs from the svn commit command in only creating a commit in your local clone of the repository, it does not merge the changes into the central repository. This allows you to queue up a series of small changes before merging them into the central repository.

Files in a git repository can be in various states:
* Untracked: Files in your local repository directory that Git is not tracking changes to and are not in the central repository.
* Tracked: Files that git tracks changes to.
* Unstaged: Tracked files that have had modifications to them but have not yet been staged or committed.
* Staged: Tracked files that have had modifications made to them and have been marked to be included in the next commit
* Committed: Files that git is tracking and that have been included in a local commit that may or may not be included in the central repository.

Note that different versions of a file can be in the Untracked and Tracked states at the same time.

This difference between staged and unstaged changes allows you to choose what changes you want in each commit.

To see what the current status of your local repository is:

git status

This will show you the status as follows;

# On branch master
# Your branch is ahead of 'origin/master' by 1 commit.
#
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: kstagedfile.h
#
# Changed but not updated:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: kchangedfile.h
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# kuntrackedfile.txt

To add a changed file to the staging area, or to add a new file to be tracked by the repository:

git add <filename>

To delete a file from the repository and add the deletion to the staging area:

git rm <filename>

To reset an unstaged or staged file to the currently committed version and irretrievably throw away you current changes:

git checkout <filename>

To reset all unstaged or staged file to the currently committed version and irretrievably throw away you current changes:

git

The git commit command adds all files in the staging state into a new commit:

git commit

If you have only changed tracked files then you can automatically add all tracked files that have been changed into staging and commit all the staged files in one command:

git commit -a

=== Seeing What You Changed ===

To see a list of what files have been changed but not yet committed:

git status

To see what code changes have been made but not yet staged:

git diff
git diff <filename>

To see what code changes have been staged but not committed:

git diff --staged
git diff --staged <filename>

To see all the commits made:

git log

To see what changes were made in a commit:

git show <sha5>

The Git diff, log and show commands have many options for changing what is shown. In particular diff can show the difference between any two commits.

=== Merging Your Changes ===

== Local Feature Development ==

== Local Bug Fixing ==

If your bug fix is only for unstable master then no special actions are required, just follow the same steps as the feature development workflow above.

If your bug fix is for a stable branch then this cannot be done without using git branches. The steps required will be given below but not explained in any detail. If possible it is recommended you wait until you are familiar with using the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

The steps detailed below are very inefficient as they use the same build tree and environment for unstable and stable which may cause a lot of rebuilding. A more efficient method is detailed in the [[Development/Git/Feature_Branch_Workflow|Feature Branch Workflow]].

First, find out the name of the stable branch you want to bug fix:

git branch -r

This will list all the branches on the central repository, for example kdelibs includes the following branches:

origin/HEAD -> origin/master
origin/KDE/4.5
origin/KDE/4.6
origin/kdecore/klocale-win
origin/kdeui/kdatetimeedit
origin/master

Here origin/KDE/4.6 is the 4.6 release of kdelibs which we will use for this example.

Next, create a local branch pointing to the stable release branch you want to bug fix:

git branch --track KDE/4.6 origin/KDE/4.6
git checkout KDE/4.6

If you have previously created the stable branch and want to do a new bug fix, then simply check it out again and update it:

git checkout KDE/4.6
git pull --rebase

Now make your required changes to the code, build and test. Once done commit the code changes to your local repository, remembering to include the BUG: and FIXED-IN: keywords in the commit message:

git commit -a

Make a note of the sha5 of the commit as you will need it later to copy the commit to the unstable master branch.

Now you can merge your changes into the central code repository:

git pull --rebase
git push origin KDE/4.6:KDE/4.6 //TODO or use git merge???

The next step is to apply the bug fix to the unstable master branch. First check the master branch back out and update it:

git checkout master
git pull --rebase

Next, Git makes it easy to apply the existing bug fix from the stable branch by using the cherry-pick command:

git cherry-pick -x -e <sha5 of stable commit>

This will allow you to edit the commit message as required before the change is committed. If the patch does not apply cleanly a message will appear and the changes will not be committed. You will then have to edit the changes and finish the commit manually.

Once cleanly applied and committed you can build and test the change, then merge them into the central code repository:

git pull --rebase
git push origin master:master //TODO or use git merge???

Development/Git/Simple Workflow

2011-06-12T13:13:38Z

Odysseus: /* Clone your repository */

Development/Git/Simple Workflow

2011-06-11T16:59:34Z

Odysseus: /* Seeing What You Changed */

Development/Git/Simple Workflow

2011-06-11T16:49:26Z

Odysseus: /* Basic Actions */

Development/Git/Simple Workflow

2011-06-11T16:18:10Z

Odysseus: /* Basic Actions */

Development/Git/Simple Workflow

2011-06-11T15:25:56Z

Odysseus: /* Committing Your Changes */

Development/Git/Simple Workflow

2011-06-11T14:53:00Z

Odysseus: /* Committing Your Changes */

Development/Git/Simple Workflow

2011-06-11T14:29:24Z

Odysseus: /* Seeing What You Changed */

Development/Git/Simple Workflow

2011-06-11T14:20:27Z

Odysseus: /* Local Bug Fixing */

Development/Git/Simple Workflow

2011-06-11T13:40:52Z

Odysseus: /* Local Bug Fixing */

Development/Git/Simple Workflow

2011-06-11T13:36:39Z

Odysseus: /* Clone your repository */

Development/Git/Simple Workflow

2011-06-11T13:35:03Z

Odysseus:

Development/Git/Feature Branch Workflow

2011-06-11T13:05:31Z

Odysseus: Created page with 'THIS IS A DRAFT, DO NOT USE! = Simple Feature Branch Workflow = This Git Workflow is designed to be followed by a new Git user who needs a simple workflow for bug fixes and new...'

THIS IS A DRAFT, DO NOT USE!

= Simple Feature Branch Workflow =

This Git Workflow is designed to be followed by a new Git user who needs a simple workflow for bug fixes and new features in a manner similar to the old SVN workflow.

Note that each module may choose to adopt a more complex workflow and you should check with your modules maintainers if this is the case.

The worked examples given will be for an imaginary app called KFoo in a git.kde.org repository called 'kfoo'.

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow the [[Development/Git/Configuration|KDE Git Configuration]] page.

=== Clone your repository ===

You need to copy your repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>

In our KFoo example:

git clone kde:kfoo

See the [[Getting_Started/Build/Environment#Source_Path|KDE Build Environment]] page for advice on structuring your source directory.

If you have a slow internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the projects.kde.org Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Basic Actions ==

This section documents basic actions that are performed within your workflow.

See also the [[Development/Git/Recipes|KDE Git Recipes]] page.

=== Create a Work Branch ===

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

To see what local branches you have:

git branch

To see all local and remote branches:

git branch -a

To create a new local branch:

git branch <new-branch>
git checkout <new-branch>

This will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' and is recommended for most branches:

git branch --track <local-branch> <remote-branch>

For our KFoo example:

git branch --track new-bar-feature origin/master

=== Commit Your Changes ===

=== Push Your Changes ===

== Local Feature Development ==

This example workflow is for locally working on new features in unstable branch and pushing them to the central repository.

This workflow is only recommended for small features or where you are the only developer on a project.

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, the KFoo app may have the following branches on the central repository:

origin/master
origin/feature/hot-new-stuff
origin/feature/cool-newer-stuff
origin/release/1.0
origin/release/1.1
origin/release/2.0

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

Two workflow's are described here, a basic workflow for small apps or where bug-fixes are infrequent, and an advanced workflow for larger apps or more frequent bug-fixes.

=== Basic Bug Fix Workflow ===

To make bug fixes on the 2.0 release you could simply checkout a local copy of the origin/release/2.0 branch and make you bug fixes there:

git branch --track bug-fix-2.0 origin/release/2.0
git checkout bug-fix-2.0
<make changes, build, test>
git commit -a
git push origin bug-fix-2.0:release/2.0
git branch --track bug-fix-master origin/master
git checkout bug-fix-master
git cherry-pick -x -e <sha5 of stable commit>
<build, test>
git push origin bug-fix-master:master

=== Advanced Bug Fix Workflow ===

the basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

This workflow uses the [[http://techbase.kde.org/Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for stable and unstable branches. This depends on you setting different up KDE Environments for the separate builds.

Development/Git/Simple Workflow

2011-06-11T13:05:00Z

Odysseus:

Development/Git/Simple Workflow

2011-06-11T13:04:04Z

Odysseus:

DANGER WILL ROBINSON!!! THIS IS AN INCOMPLETE DRAFT!!!

= Simple Workflow =

This workflow is designed to be as close as possible to the KDE SVN Workflow. It is only recommended to be used for the first week or two of using Git with KDE while you become familiar with the basic Git commands. Once comfortable with the basic commands you should then move onto the Simple Feature Branch Workflow.

The worked examples given will be for an imaginary app called KFoo in a git.kde.org repository called 'kfoo'.

More detailed information can be found on the main [[Development/Git|KDE Git page]].

= Simple Feature Branch Workflow =

This Git Workflow is designed to be followed by a new Git user who needs a simple workflow for bug fixes and new features in a manner similar to the old SVN workflow.

Note that each module may choose to adopt a more complex workflow and you should check with your modules maintainers if this is the case.

The worked examples given will be for an imaginary app called KFoo in a git.kde.org repository called 'kfoo'.

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow the [[Development/Git/Configuration|KDE Git Configuration]] page.

=== Clone your repository ===

You need to copy your repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>

In our KFoo example:

git clone kde:kfoo

See the [[Getting_Started/Build/Environment#Source_Path|KDE Build Environment]] page for advice on structuring your source directory.

If you have a slow internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the projects.kde.org Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Basic Actions ==

This section documents basic actions that are performed within your workflow.

See also the [[Development/Git/Recipes|KDE Git Recipes]] page.

=== Create a Work Branch ===

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

To see what local branches you have:

git branch

To see all local and remote branches:

git branch -a

To create a new local branch:

git branch <new-branch>
git checkout <new-branch>

This will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' and is recommended for most branches:

git branch --track <local-branch> <remote-branch>

For our KFoo example:

git branch --track new-bar-feature origin/master

=== Commit Your Changes ===

=== Push Your Changes ===

== Local Feature Development ==

This example workflow is for locally working on new features in unstable branch and pushing them to the central repository.

This workflow is only recommended for small features or where you are the only developer on a project.

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, the KFoo app may have the following branches on the central repository:

origin/master
origin/feature/hot-new-stuff
origin/feature/cool-newer-stuff
origin/release/1.0
origin/release/1.1
origin/release/2.0

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

Two workflow's are described here, a basic workflow for small apps or where bug-fixes are infrequent, and an advanced workflow for larger apps or more frequent bug-fixes.

=== Basic Bug Fix Workflow ===

To make bug fixes on the 2.0 release you could simply checkout a local copy of the origin/release/2.0 branch and make you bug fixes there:

git branch --track bug-fix-2.0 origin/release/2.0
git checkout bug-fix-2.0
<make changes, build, test>
git commit -a
git push origin bug-fix-2.0:release/2.0
git branch --track bug-fix-master origin/master
git checkout bug-fix-master
git cherry-pick -x -e <sha5 of stable commit>
<build, test>
git push origin bug-fix-master:master

=== Advanced Bug Fix Workflow ===

the basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

This workflow uses the [[http://techbase.kde.org/Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for stable and unstable branches. This depends on you setting different up KDE Environments for the separate builds.

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow the [[Development/Git/Configuration|KDE Git Configuration]] page.

=== Clone your repository ===

You need to copy your repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>

In our KFoo example:

git clone kde:kfoo

See the [[Getting_Started/Build/Environment#Source_Path|KDE Build Environment]] page for advice on structuring your source directory.

If you have a slow internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the projects.kde.org Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Basic Actions ==

This section documents basic actions that are performed within your workflow.

See also the [[Development/Git/Recipes|KDE Git Recipes]] page.

=== Create a Work Branch ===

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

To see what local branches you have:

git branch

To see all local and remote branches:

git branch -a

To create a new local branch:

git branch <new-branch>
git checkout <new-branch>

This will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' and is recommended for most branches:

git branch --track <local-branch> <remote-branch>

For our KFoo example:

git branch --track new-bar-feature origin/master

=== Commit Your Changes ===

=== Push Your Changes ===

== Local Feature Development ==

This example workflow is for locally working on new features in unstable branch and pushing them to the central repository.

This workflow is only recommended for small features or where you are the only developer on a project.

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, the KFoo app may have the following branches on the central repository:

origin/master
origin/feature/hot-new-stuff
origin/feature/cool-newer-stuff
origin/release/1.0
origin/release/1.1
origin/release/2.0

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

Two workflow's are described here, a basic workflow for small apps or where bug-fixes are infrequent, and an advanced workflow for larger apps or more frequent bug-fixes.

=== Basic Bug Fix Workflow ===

To make bug fixes on the 2.0 release you could simply checkout a local copy of the origin/release/2.0 branch and make you bug fixes there:

git branch --track bug-fix-2.0 origin/release/2.0
git checkout bug-fix-2.0
<make changes, build, test>
git commit -a
git push origin bug-fix-2.0:release/2.0
git branch --track bug-fix-master origin/master
git checkout bug-fix-master
git cherry-pick -x -e <sha5 of stable commit>
<build, test>
git push origin bug-fix-master:master

=== Advanced Bug Fix Workflow ===

the basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

This workflow uses the [[http://techbase.kde.org/Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for stable and unstable branches. This depends on you setting different up KDE Environments for the separate builds.

Development/Review Board

2011-06-10T18:32:22Z

Odysseus: /* Using post-review to post changes for review */

= KDE Review Board =

KDE currently uses the [http://www.reviewboard.org/ Review Board] software for performing reviews on code changes.

There are separate versions of Review Board for use with Git and Subversion:
* [http://git.reviewboard.kde.org KDE Git Review Board]
* [http://svn.reviewboard.kde.org KDE Subversion Review Board]

Note that http://reviewboard.kde.org/ redirects to the Git version.

== Using Review Board and post-review with Git ==

Every Git Project repository has its own entry on the KDE Git Review Board.

=== Creating your changeset ===

To create your changeset, you probably want to work in a separate branch - or even in your clone. This is actually suggested and the proper way to do changesets in Git. You can create any number of commits, amend them, and do whatever you want to do - it won't affect the next steps, as you will submit the whole branch for review.

Before proceeding it is good practice to rebase your branch onto the branch you want to target for the merge. So, supposing you want to target <tt>master</tt>, make sure it is up-to-date with the remote and then run, and want to publish a review for a local branch:

git pull --rebase

If you want to post a review for merging a non local branch, you might want to run the following:

git merge master

=== Using post-review to post changes for review ===

Once you are done with the above, it is time to post the changes to ReviewBoard. The easiest and most comfortable way to do that is <tt>[http://www.reviewboard.org/docs/manual/dev/users/tools/post-review/ post-review]</tt>, a handy command line tool which takes care of creating review requests for you. This is normally in a package called RBTools (openSuse has a 1-click package in the [http://software.opensuse.org/search?q=rbtools devel:tools repository])

==== Prerequisites ====

The following has to be done only once to make your local clone fit for use with <tt>post-review</tt>.

First of all, you have to tell it about the ReviewBoard server. If your project does not ship with a <tt>.reviewboardrc</tt> file (encourage the project manager to add one!), the first thing you have to run is:

git config reviewboard.url https://git.reviewboard.kde.org

ReviewBoard currently only knows the project repositories by their git:// URLs, making it necessary to have a remote using the git:// URL in your clone. If your <tt>origin</tt> remote is already using the git:// URL, you are all set. If not you need to add another remote now.

Let's suppose you are looking to have some changes to [https://projects.kde.org/projects/extragear/multimedia/amarok Amarok] reviewed, and the URL of your <tt>origin</tt> remote is <tt>git@git.kde.org:amarok</tt>. To add another remote using the git:// URL you might run:

git remote add anonupstream git://anongit.kde.org/amarok
git fetch anonupstream

If your <tt>origin</tt> remote was already using the git:// url, substitute <tt>anonupstream</tt> with <tt>origin</tt> throughout the rest of this tutorial.

==== Creating the review request ====

You are now ready to create the review request. The <tt>post-review</tt> command should look something like this:

post-review --parent=master --tracking-branch=anonupstream/master

This command tells <tt>post-review</tt> that your branch is based upon <tt>master</tt>, and it is set to track the remote branch <tt>anonupstream/master</tt>. You can also give <tt>post-review</tt> some more arguments to avoid using the web interface later - have a look at the [http://www.reviewboard.org/docs/manual/dev/users/tools/post-review/ user manual] for more on that.

After the command has been run a web address will be shown in the terminal, pointing at your review request.

==== Updating a review request ====

If you need to update an existing review request you can invoke <tt>post-review</tt> with an additional <tt>-r</tt> argument, which should be the numeric id of the review request you want to update. Supposing you want to update review request 54, you would run:

post-review --parent=master --tracking-branch=anonupstream/master -r 54

==== Creating a ReviewBoard-compatible diff ====

In some rare cases you simply want to generate a diff and submit it to ReviewBoard later. You can do that by running:

post-review --parent=master -n > your-patch.patch

=== Closing a review request ===

To close a review request, you can either use the ReviewBoard web interface or more conveniently, right in a commit. This is done by using the REVIEW keyword followed by the review ID you want to close. For example, to close review 54, you would put

REVIEW: 54

in your commit. A message will also be posted to ReviewBoard indicating the commit SHA1 that closed the request.

== Using Review Board With Subversion ==

Not all KDE Subversion projects use Review Board so first you need to check if the project you've created the patch for is actually using reviewboard. For this, go to the [http://svn.reviewboard.kde.org/groups/ groups section] and see if the project's group is listed there. If it is listed there, you should use the reviewboard, otherwise send the patch by other means.

For sending a patch, you first need to register. Then simply click ''[http://svn.reviewboard.kde.org/r/new/ New Review Request]'' and fill out the form. The most important parts of the form are:

* '''The actual patch'''. You need to upload the patch you've created earlier here
* '''The SVN base path'''. This is needed for the inline patch display to work. This can be a bit tricky, if you are unfamiliar with KDE's SVN layout, check [http://websvn.kde.org WebSVN]. For example, if you're ''svn diff'ing'' from <tt>/path/to/your/copy/of/kdelibs/cmake/modules</tt>, the base path should be <tt>/trunk/KDE/kdelibs/cmake/modules</tt>. If you still don't know the correct base path, ask a developer on IRC. You can also edit the review request later.
* '''A summary of the patch'''. This should be short, it will show up as subject of the notification emails.
* '''A description of the patch'''. This can be longer.
* '''The group(s)'''. Make sure you enter the correct group '''ID''' here, as seen earlier on the [http://reviewboard.kde.org/groups/ groups page].

After you completed the form, a notification mail will be sent to the developers and they will answer you.

/!\ You need to use svn diff in english, if your system is not english, please do LC_ALL=C svn diff

Development/Review Board

2011-06-10T18:31:58Z

Odysseus: /* KDE Review Board */

= KDE Review Board =

KDE currently uses the [http://www.reviewboard.org/ Review Board] software for performing reviews on code changes.

There are separate versions of Review Board for use with Git and Subversion:
* [http://git.reviewboard.kde.org KDE Git Review Board]
* [http://svn.reviewboard.kde.org KDE Subversion Review Board]

Note that http://reviewboard.kde.org/ redirects to the Git version.

== Using Review Board and post-review with Git ==

Every Git Project repository has its own entry on the KDE Git Review Board.

=== Creating your changeset ===

To create your changeset, you probably want to work in a separate branch - or even in your clone. This is actually suggested and the proper way to do changesets in Git. You can create any number of commits, amend them, and do whatever you want to do - it won't affect the next steps, as you will submit the whole branch for review.

Before proceeding it is good practice to rebase your branch onto the branch you want to target for the merge. So, supposing you want to target <tt>master</tt>, make sure it is up-to-date with the remote and then run, and want to publish a review for a local branch:

git pull --rebase

If you want to post a review for merging a non local branch, you might want to run the following:

git merge master

=== Using post-review to post changes for review ===

Once you are done with the above, it is time to post the changes to ReviewBoard. The easiest and most comfortable way to do that is <tt>[http://www.reviewboard.org/docs/manual/dev/users/tools/post-review/ post-review]</tt>, a handy command line tool which takes care of creating review requests for you. This is normally in a package called RBTools (openSuse has a 1-click package in the [[http://software.opensuse.org/search?q=rbtools devel:tools repository]])

==== Prerequisites ====

The following has to be done only once to make your local clone fit for use with <tt>post-review</tt>.

First of all, you have to tell it about the ReviewBoard server. If your project does not ship with a <tt>.reviewboardrc</tt> file (encourage the project manager to add one!), the first thing you have to run is:

git config reviewboard.url https://git.reviewboard.kde.org

ReviewBoard currently only knows the project repositories by their git:// URLs, making it necessary to have a remote using the git:// URL in your clone. If your <tt>origin</tt> remote is already using the git:// URL, you are all set. If not you need to add another remote now.

Let's suppose you are looking to have some changes to [https://projects.kde.org/projects/extragear/multimedia/amarok Amarok] reviewed, and the URL of your <tt>origin</tt> remote is <tt>git@git.kde.org:amarok</tt>. To add another remote using the git:// URL you might run:

git remote add anonupstream git://anongit.kde.org/amarok
git fetch anonupstream

If your <tt>origin</tt> remote was already using the git:// url, substitute <tt>anonupstream</tt> with <tt>origin</tt> throughout the rest of this tutorial.

==== Creating the review request ====

You are now ready to create the review request. The <tt>post-review</tt> command should look something like this:

post-review --parent=master --tracking-branch=anonupstream/master

This command tells <tt>post-review</tt> that your branch is based upon <tt>master</tt>, and it is set to track the remote branch <tt>anonupstream/master</tt>. You can also give <tt>post-review</tt> some more arguments to avoid using the web interface later - have a look at the [http://www.reviewboard.org/docs/manual/dev/users/tools/post-review/ user manual] for more on that.

After the command has been run a web address will be shown in the terminal, pointing at your review request.

==== Updating a review request ====

If you need to update an existing review request you can invoke <tt>post-review</tt> with an additional <tt>-r</tt> argument, which should be the numeric id of the review request you want to update. Supposing you want to update review request 54, you would run:

post-review --parent=master --tracking-branch=anonupstream/master -r 54

==== Creating a ReviewBoard-compatible diff ====

In some rare cases you simply want to generate a diff and submit it to ReviewBoard later. You can do that by running:

post-review --parent=master -n > your-patch.patch

=== Closing a review request ===

To close a review request, you can either use the ReviewBoard web interface or more conveniently, right in a commit. This is done by using the REVIEW keyword followed by the review ID you want to close. For example, to close review 54, you would put

REVIEW: 54

in your commit. A message will also be posted to ReviewBoard indicating the commit SHA1 that closed the request.

== Using Review Board With Subversion ==

Not all KDE Subversion projects use Review Board so first you need to check if the project you've created the patch for is actually using reviewboard. For this, go to the [http://svn.reviewboard.kde.org/groups/ groups section] and see if the project's group is listed there. If it is listed there, you should use the reviewboard, otherwise send the patch by other means.

For sending a patch, you first need to register. Then simply click ''[http://svn.reviewboard.kde.org/r/new/ New Review Request]'' and fill out the form. The most important parts of the form are:

* '''The actual patch'''. You need to upload the patch you've created earlier here
* '''The SVN base path'''. This is needed for the inline patch display to work. This can be a bit tricky, if you are unfamiliar with KDE's SVN layout, check [http://websvn.kde.org WebSVN]. For example, if you're ''svn diff'ing'' from <tt>/path/to/your/copy/of/kdelibs/cmake/modules</tt>, the base path should be <tt>/trunk/KDE/kdelibs/cmake/modules</tt>. If you still don't know the correct base path, ask a developer on IRC. You can also edit the review request later.
* '''A summary of the patch'''. This should be short, it will show up as subject of the notification emails.
* '''A description of the patch'''. This can be longer.
* '''The group(s)'''. Make sure you enter the correct group '''ID''' here, as seen earlier on the [http://reviewboard.kde.org/groups/ groups page].

After you completed the form, a notification mail will be sent to the developers and they will answer you.

/!\ You need to use svn diff in english, if your system is not english, please do LC_ALL=C svn diff

Development/Review Board

2011-06-10T18:28:23Z

Odysseus: /* Using post-review to post changes for review */

= KDE Review Board =

KDE currently uses the [http://www.reviewboard.org/ Review Board] software for performing reviews on code changes.

There are separate versions of Review Board for use with Git and Subversion:
* [http://git.reviewboard.kde.org KDE Git Review Board]
* [http://svn.reviewboard.kde.org KDE Subversion Review Board]

Note that currently http://reviewboard.kde.org/ defaults to the Subversion version but this is scheduled to change so it is recommended to always use the git or svn prefix to be sure.

== Using ReviewBoard and post-review with Git ==

Every Git Project repository has its own entry on the KDE Git Review Board.

=== Creating your changeset ===

To create your changeset, you probably want to work in a separate branch - or even in your clone. This is actually suggested and the proper way to do changesets in Git. You can create any number of commits, amend them, and do whatever you want to do - it won't affect the next steps, as you will submit the whole branch for review.

Before proceeding it is good practice to rebase your branch onto the branch you want to target for the merge. So, supposing you want to target <tt>master</tt>, make sure it is up-to-date with the remote and then run, and want to publish a review for a local branch:

git rebase master

If you want to post a review for merging a non local branch, you might want to run the following:

git merge master

=== Using post-review to post changes for review ===

Once you are done with the above, it is time to post the changes to ReviewBoard. The easiest and most comfortable way to do that is <tt>[http://www.reviewboard.org/docs/manual/dev/users/tools/post-review/ post-review]</tt>, a handy command line tool which takes care of creating review requests for you. This is normally in a package called RBTools (openSuse has a 1-click package in the [[http://software.opensuse.org/search?q=rbtools devel:tools repository]])

==== Prerequisites ====

The following has to be done only once to make your local clone fit for use with <tt>post-review</tt>.

First of all, you have to tell it about the ReviewBoard server. If your project does not ship with a <tt>.reviewboardrc</tt> file (encourage the project manager to add one!), the first thing you have to run is:

git config reviewboard.url https://git.reviewboard.kde.org

ReviewBoard currently only knows the project repositories by their git:// URLs, making it necessary to have a remote using the git:// URL in your clone. If your <tt>origin</tt> remote is already using the git:// URL, you are all set. If not you need to add another remote now.

Let's suppose you are looking to have some changes to [https://projects.kde.org/projects/extragear/multimedia/amarok Amarok] reviewed, and the URL of your <tt>origin</tt> remote is <tt>git@git.kde.org:amarok</tt>. To add another remote using the git:// URL you might run:

git remote add anonupstream git://anongit.kde.org/amarok
git fetch anonupstream

If your <tt>origin</tt> remote was already using the git:// url, substitute <tt>anonupstream</tt> with <tt>origin</tt> throughout the rest of this tutorial.

==== Creating the review request ====

You are now ready to create the review request. The <tt>post-review</tt> command should look something like this:

post-review --parent=master --tracking-branch=anonupstream/master

This command tells <tt>post-review</tt> that your branch is based upon <tt>master</tt>, and it is set to track the remote branch <tt>anonupstream/master</tt>. You can also give <tt>post-review</tt> some more arguments to avoid using the web interface later - have a look at the [http://www.reviewboard.org/docs/manual/dev/users/tools/post-review/ user manual] for more on that.

After the command has been run a web address will be shown in the terminal, pointing at your review request.

==== Updating a review request ====

If you need to update an existing review request you can invoke <tt>post-review</tt> with an additional <tt>-r</tt> argument, which should be the numeric id of the review request you want to update. Supposing you want to update review request 54, you would run:

post-review --parent=master --tracking-branch=anonupstream/master -r 54

==== Creating a ReviewBoard-compatible diff ====

In some rare cases you simply want to generate a diff and submit it to ReviewBoard later. You can do that by running:

post-review --parent=master -n > your-patch.patch

=== Closing a review request ===

To close a review request, you can either use the ReviewBoard web interface or more conveniently, right in a commit. This is done by using the REVIEW keyword followed by the review ID you want to close. For example, to close review 54, you would put

REVIEW: 54

in your commit. A message will also be posted to ReviewBoard indicating the commit SHA1 that closed the request.

== Using Review Board With Subversion ==

Not all KDE Subversion projects use Review Board so first you need to check if the project you've created the patch for is actually using reviewboard. For this, go to the [http://svn.reviewboard.kde.org/groups/ groups section] and see if the project's group is listed there. If it is listed there, you should use the reviewboard, otherwise send the patch by other means.

For sending a patch, you first need to register. Then simply click ''[http://svn.reviewboard.kde.org/r/new/ New Review Request]'' and fill out the form. The most important parts of the form are:

* '''The actual patch'''. You need to upload the patch you've created earlier here
* '''The SVN base path'''. This is needed for the inline patch display to work. This can be a bit tricky, if you are unfamiliar with KDE's SVN layout, check [http://websvn.kde.org WebSVN]. For example, if you're ''svn diff'ing'' from <tt>/path/to/your/copy/of/kdelibs/cmake/modules</tt>, the base path should be <tt>/trunk/KDE/kdelibs/cmake/modules</tt>. If you still don't know the correct base path, ask a developer on IRC. You can also edit the review request later.
* '''A summary of the patch'''. This should be short, it will show up as subject of the notification emails.
* '''A description of the patch'''. This can be longer.
* '''The group(s)'''. Make sure you enter the correct group '''ID''' here, as seen earlier on the [http://reviewboard.kde.org/groups/ groups page].

After you completed the form, a notification mail will be sent to the developers and they will answer you.

/!\ You need to use svn diff in english, if your system is not english, please do LC_ALL=C svn diff

Development/Git/Simple Workflow

2011-06-06T19:17:56Z

Odysseus:

DANGER WILL ROBINSON!!! THIS IS AN INCOMPLETE DRAFT!!!

== Simple Workflow ==

This workflow is designed to be as close as possible to the KDE SVN Workflow. It is only recommended to be used for the first few weeks of using Git with KDE while you learn how Git works. Once comfortable with the basic commands you should then move onto the Simple Feature Branch Workflow.

== Simple Feature Branch Workflow ==

This Git Workflow is designed to be followed by a new Git user who needs a simple workflow for bug fixes and new features in a manner similar to the old SVN workflow.

Note that each module may choose to adopt a more complex workflow and you should check with your modules maintainers if this is the case.

The worked examples given will be for an imaginary app called KFoo in a git.kde.org repository called 'kfoo'.

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow the [[Development/Git/Configuration|KDE Git Configuration]] page.

=== Clone your repository ===

You need to copy your repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>

In our KFoo example:

git clone kde:kfoo

See the [[Getting_Started/Build/Environment#Source_Path|KDE Build Environment]] page for advice on structuring your source directory.

If you have a slow internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the projects.kde.org Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Basic Actions ==

This section documents basic actions that are performed within your workflow.

See also the [[Development/Git/Recipes|KDE Git Recipes]] page.

=== Create a Work Branch ===

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

To see what local branches you have:

git branch

To see all local and remote branches:

git branch -a

To create a new local branch:

git branch <new-branch>
git checkout <new-branch>

This will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' and is recommended for most branches:

git branch --track <local-branch> <remote-branch>

For our KFoo example:

git branch --track new-bar-feature origin/master

=== Commit Your Changes ===

=== Push Your Changes ===

== Local Feature Development ==

This example workflow is for locally working on new features in unstable branch and pushing them to the central repository.

This workflow is only recommended for small features or where you are the only developer on a project.

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, the KFoo app may have the following branches on the central repository:

origin/master
origin/feature/hot-new-stuff
origin/feature/cool-newer-stuff
origin/release/1.0
origin/release/1.1
origin/release/2.0

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

Two workflow's are described here, a basic workflow for small apps or where bug-fixes are infrequent, and an advanced workflow for larger apps or more frequent bug-fixes.

=== Basic Bug Fix Workflow ===

To make bug fixes on the 2.0 release you could simply checkout a local copy of the origin/release/2.0 branch and make you bug fixes there:

git branch --track bug-fix-2.0 origin/release/2.0
git checkout bug-fix-2.0
<make changes, build, test>
git commit -a
git push origin bug-fix-2.0:release/2.0
git branch --track bug-fix-master origin/master
git checkout bug-fix-master
git cherry-pick -x -e <sha5 of stable commit>
<build, test>
git push origin bug-fix-master:master

=== Advanced Bug Fix Workflow ===

the basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

This workflow uses the [[http://techbase.kde.org/Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for stable and unstable branches. This depends on you setting different up KDE Environments for the separate builds.

Development/Git/Simple Workflow

2011-06-05T13:54:46Z

Odysseus: /* Simple KDE Git Workflow */

DANGER WILL ROBINSON!!! THIS IS AN INCOMPLETE DRAFT!!!

== Simple KDE Git Workflow ==

This Git Workflow is designed to be followed by a new Git user who needs a simple workflow for bug fixes and new features in a manner similar to the old SVN workflow.

Note that each module may choose to adopt a more complex workflow and you should check with your modules maintainers if this is the case.

The worked examples given will be for an imaginary app called KFoo in a git.kde.org repository called 'kfoo'.

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow the [[Development/Git/Configuration|KDE Git Configuration]] page.

=== Clone your repository ===

You need to copy your repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>

In our KFoo example:

git clone kde:kfoo

See the [[Getting_Started/Build/Environment#Source_Path|KDE Build Environment]] page for advice on structuring your source directory.

If you have a slow internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the projects.kde.org Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Basic Actions ==

This section documents basic actions that are performed within your workflow.

See also the [[Development/Git/Recipes|KDE Git Recipes]] page.

=== Create a Work Branch ===

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

To see what local branches you have:

git branch

To see all local and remote branches:

git branch -a

To create a new local branch:

git branch <new-branch>
git checkout <new-branch>

This will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' and is recommended for most branches:

git branch --track <local-branch> <remote-branch>

For our KFoo example:

git branch --track new-bar-feature origin/master

=== Commit Your Changes ===

=== Push Your Changes ===

== Local Feature Development ==

This example workflow is for locally working on new features in unstable branch and pushing them to the central repository.

This workflow is only recommended for small features or where you are the only developer on a project.

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, the KFoo app may have the following branches on the central repository:

origin/master
origin/feature/hot-new-stuff
origin/feature/cool-newer-stuff
origin/release/1.0
origin/release/1.1
origin/release/2.0

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

Two workflow's are described here, a basic workflow for small apps or where bug-fixes are infrequent, and an advanced workflow for larger apps or more frequent bug-fixes.

=== Basic Bug Fix Workflow ===

To make bug fixes on the 2.0 release you could simply checkout a local copy of the origin/release/2.0 branch and make you bug fixes there:

git branch --track bug-fix-2.0 origin/release/2.0
git checkout bug-fix-2.0
<make changes, build, test>
git commit -a
git push origin bug-fix-2.0:release/2.0
git branch --track bug-fix-master origin/master
git checkout bug-fix-master
git cherry-pick -x -e <sha5 of stable commit>
<build, test>
git push origin bug-fix-master:master

=== Advanced Bug Fix Workflow ===

the basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

This workflow uses the [[http://techbase.kde.org/Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for stable and unstable branches. This depends on you setting different up KDE Environments for the separate builds.

Development/Git/Simple Workflow

2011-06-05T13:53:22Z

Odysseus: /* Clone your repository */

== Simple KDE Git Workflow ==

This Git Workflow is designed to be followed by a new Git user who needs a simple workflow for bug fixes and new features in a manner similar to the old SVN workflow.

Note that each module may choose to adopt a more complex workflow and you should check with your modules maintainers if this is the case.

The worked examples given will be for an imaginary app called KFoo in a git.kde.org repository called 'kfoo'.

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow the [[Development/Git/Configuration|KDE Git Configuration]] page.

=== Clone your repository ===

You need to copy your repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>

In our KFoo example:

git clone kde:kfoo

See the [[Getting_Started/Build/Environment#Source_Path|KDE Build Environment]] page for advice on structuring your source directory.

If you have a slow internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the projects.kde.org Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Basic Actions ==

This section documents basic actions that are performed within your workflow.

See also the [[Development/Git/Recipes|KDE Git Recipes]] page.

=== Create a Work Branch ===

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

To see what local branches you have:

git branch

To see all local and remote branches:

git branch -a

To create a new local branch:

git branch <new-branch>
git checkout <new-branch>

This will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' and is recommended for most branches:

git branch --track <local-branch> <remote-branch>

For our KFoo example:

git branch --track new-bar-feature origin/master

=== Commit Your Changes ===

=== Push Your Changes ===

== Local Feature Development ==

This example workflow is for locally working on new features in unstable branch and pushing them to the central repository.

This workflow is only recommended for small features or where you are the only developer on a project.

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, the KFoo app may have the following branches on the central repository:

origin/master
origin/feature/hot-new-stuff
origin/feature/cool-newer-stuff
origin/release/1.0
origin/release/1.1
origin/release/2.0

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

Two workflow's are described here, a basic workflow for small apps or where bug-fixes are infrequent, and an advanced workflow for larger apps or more frequent bug-fixes.

=== Basic Bug Fix Workflow ===

To make bug fixes on the 2.0 release you could simply checkout a local copy of the origin/release/2.0 branch and make you bug fixes there:

git branch --track bug-fix-2.0 origin/release/2.0
git checkout bug-fix-2.0
<make changes, build, test>
git commit -a
git push origin bug-fix-2.0:release/2.0
git branch --track bug-fix-master origin/master
git checkout bug-fix-master
git cherry-pick -x -e <sha5 of stable commit>
<build, test>
git push origin bug-fix-master:master

=== Advanced Bug Fix Workflow ===

the basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

This workflow uses the [[http://techbase.kde.org/Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for stable and unstable branches. This depends on you setting different up KDE Environments for the separate builds.

Development/Git/Simple Workflow

2011-06-05T13:51:05Z

Odysseus: /* Local Bug Fixing */

== Simple KDE Git Workflow ==

This Git Workflow is designed to be followed by a new Git user who needs a simple workflow for bug fixes and new features in a manner similar to the old SVN workflow.

Note that each module may choose to adopt a more complex workflow and you should check with your modules maintainers if this is the case.

The worked examples given will be for an imaginary app called KFoo in a git.kde.org repository called 'kfoo'.

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow the [[Development/Git/Configuration|KDE Git Configuration]] page.

=== Clone your repository ===

You need to copy your repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>

In our KFoo example:

git clone kde:kfoo

See the [[Getting_Started/Build/Environment#Source_Path]] page for advice on structuring your source directory.

If you have a slow internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the projects.kde.org Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Basic Actions ==

This section documents basic actions that are performed within your workflow.

See also the [[Development/Git/Recipes|KDE Git Recipes]] page.

=== Create a Work Branch ===

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

To see what local branches you have:

git branch

To see all local and remote branches:

git branch -a

To create a new local branch:

git branch <new-branch>
git checkout <new-branch>

This will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' and is recommended for most branches:

git branch --track <local-branch> <remote-branch>

For our KFoo example:

git branch --track new-bar-feature origin/master

=== Commit Your Changes ===

=== Push Your Changes ===

== Local Feature Development ==

This example workflow is for locally working on new features in unstable branch and pushing them to the central repository.

This workflow is only recommended for small features or where you are the only developer on a project.

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, the KFoo app may have the following branches on the central repository:

origin/master
origin/feature/hot-new-stuff
origin/feature/cool-newer-stuff
origin/release/1.0
origin/release/1.1
origin/release/2.0

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to push the bug fix to both the stable and unstable branch in the central repository.

Two workflow's are described here, a basic workflow for small apps or where bug-fixes are infrequent, and an advanced workflow for larger apps or more frequent bug-fixes.

=== Basic Bug Fix Workflow ===

To make bug fixes on the 2.0 release you could simply checkout a local copy of the origin/release/2.0 branch and make you bug fixes there:

git branch --track bug-fix-2.0 origin/release/2.0
git checkout bug-fix-2.0
<make changes, build, test>
git commit -a
git push origin bug-fix-2.0:release/2.0
git branch --track bug-fix-master origin/master
git checkout bug-fix-master
git cherry-pick -x -e <sha5 of stable commit>
<build, test>
git push origin bug-fix-master:master

=== Advanced Bug Fix Workflow ===

the basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

This workflow uses the [[http://techbase.kde.org/Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for stable and unstable branches. This depends on you setting different up KDE Environments for the separate builds.

Development/Git/Simple Workflow

2011-06-05T13:50:29Z

Odysseus: /* Local Bug Fixing */

== Simple KDE Git Workflow ==

This Git Workflow is designed to be followed by a new Git user who needs a simple workflow for bug fixes and new features in a manner similar to the old SVN workflow.

Note that each module may choose to adopt a more complex workflow and you should check with your modules maintainers if this is the case.

The worked examples given will be for an imaginary app called KFoo in a git.kde.org repository called 'kfoo'.

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow the [[Development/Git/Configuration|KDE Git Configuration]] page.

=== Clone your repository ===

You need to copy your repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>

In our KFoo example:

git clone kde:kfoo

See the [[Getting_Started/Build/Environment#Source_Path]] page for advice on structuring your source directory.

If you have a slow internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the projects.kde.org Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Basic Actions ==

This section documents basic actions that are performed within your workflow.

See also the [[Development/Git/Recipes|KDE Git Recipes]] page.

=== Create a Work Branch ===

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

To see what local branches you have:

git branch

To see all local and remote branches:

git branch -a

To create a new local branch:

git branch <new-branch>
git checkout <new-branch>

This will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' and is recommended for most branches:

git branch --track <local-branch> <remote-branch>

For our KFoo example:

git branch --track new-bar-feature origin/master

=== Commit Your Changes ===

=== Push Your Changes ===

== Local Feature Development ==

This example workflow is for locally working on new features in unstable branch and pushing them to the central repository.

This workflow is only recommended for small features or where you are the only developer on a project.

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, the KFoo app may have the following branches on the central repository:

origin/master
origin/feature/hot-new-stuff
origin/feature/cool-newer-stuff
origin/release/1.0
origin/release/1.1
origin/release/2.0

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to add the bug fix to both the stable and unstable branch in the central repository.

Two workflow's are described here, a basic workflow for small apps or where bug-fixes are infrequent, and an advanced workflow for larger apps or more frequent bug-fixes.

=== Basic Bug Fix Workflow ===

To make bug fixes on the 2.0 release you could simply checkout a local copy of the origin/release/2.0 branch and make you bug fixes there:

git branch --track bug-fix-2.0 origin/release/2.0
git checkout bug-fix-2.0
<make changes, build, test>
git commit -a
git push origin bug-fix-2.0:release/2.0
git branch --track bug-fix-master origin/master
git checkout bug-fix-master
git cherry-pick -x -e <sha5 of stable commit>
<build, test>
git push origin bug-fix-master:master

=== Advanced Bug Fix Workflow ===

the basic workflow works fine except switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem, but in most cases this constant rebuilding will be a waste of time.

This workflow uses the [[http://techbase.kde.org/Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for stable and unstable branches. This depends on you setting different up KDE Environments for the separate builds.

Development/Git/Simple Workflow

2011-06-05T13:36:10Z

Odysseus: /* Clone your repository */

== Simple KDE Git Workflow ==

This Git Workflow is designed to be followed by a new Git user who needs a simple workflow for bug fixes and new features in a manner similar to the old SVN workflow.

Note that each module may choose to adopt a more complex workflow and you should check with your modules maintainers if this is the case.

The worked examples given will be for an imaginary app called KFoo in a git.kde.org repository called 'kfoo'.

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow the [[Development/Git/Configuration|KDE Git Configuration]] page.

=== Clone your repository ===

You need to copy your repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>

In our KFoo example:

git clone kde:kfoo

See the [[Getting_Started/Build/Environment#Source_Path]] page for advice on structuring your source directory.

If you have a slow internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the projects.kde.org Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Basic Actions ==

This section documents basic actions that are performed within your workflow.

See also the [[Development/Git/Recipes|KDE Git Recipes]] page.

=== Create a Work Branch ===

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

To see what local branches you have:

git branch

To see all local and remote branches:

git branch -a

To create a new local branch:

git branch <new-branch>
git checkout <new-branch>

This will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' and is recommended for most branches:

git branch --track <local-branch> <remote-branch>

For our KFoo example:

git branch --track new-bar-feature origin/master

=== Commit Your Changes ===

=== Push Your Changes ===

== Local Feature Development ==

This example workflow is for locally working on new features in unstable branch and pushing them to the central repository.

This workflow is only recommended for small features or where you are the only developer on a project.

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, the KFoo app may have the following branches on the central repository:

origin/master
origin/feature/hot-new-stuff
origin/feature/cool-newer-stuff
origin/release/1.0
origin/release/1.1
origin/release/2.0

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to add the bug fix to the stable branch as well.

Two workflow's are described here, a basic workflow for small apps or where bug-fixes are infrequent, and an advanced workflow for larger apps or more frequent bug-fixes.

=== Basic Bug Fix Workflow ===

To make bug fixes on the 2.0 release you could simply checkout a local copy of the origin/release/2.0 branch and make you bug fixes there:

git branch --track bug-fix-2.0 origin/release/2.0
git checkout bug-fixes

However, switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem in this case you would just use the feature workflow.

This workflow uses the [[http://techbase.kde.org/Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for stable and unstable branches. This depends on you setting different up KDE Environments for the separate builds.

Development/Git/Simple Workflow

2011-06-05T13:16:36Z

Odysseus:

== Simple KDE Git Workflow ==

This Git Workflow is designed to be followed by a new Git user who needs a simple workflow for bug fixes and new features in a manner similar to the old SVN workflow.

Note that each module may choose to adopt a more complex workflow and you should check with your modules maintainers if this is the case.

The worked examples given will be for an imaginary app called KFoo in a git.kde.org repository called 'kfoo'.

== Set-up ==

This section documents how to set up Git and your code repository for development.

=== Configure Git ===

Follow the [[Development/Git/Configuration|KDE Git Configuration]] page.

=== Clone your repository ===

You need to copy your repository from git.kde.org into your local KDE source directory. In Git this process is called cloning.

To clone your project repository:

cd your/source/dir
git clone kde:<project>

In our KFoo example:

git clone kde:kfoo

See the [[Getting_Started/Build/Environment|KDE Build Environment]] page for advice on structuring your source directory.

If you have a slow internet connection then you may prefer to [[Getting_Started/Sources/Snapshots|download a snapshot tarball]] to bootstrap your clone. You can copy the required command from the projects.kde.org Repository page for your project, but it will be of the form:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

== Basic Actions ==

This section documents basic actions that are performed within your workflow.

See also the [[Development/Git/Recipes|KDE Git Recipes]] page.

=== Create a Work Branch ===

By default when you first create a repository clone there is only a single local branch called 'master'. It is not good practice to do development in master, it is better kept clean for reference. Instead all work should be performed in a new local branch, even bug fixes.

To see what local branches you have:

git branch

To see all local and remote branches:

git branch -a

To create a new local branch:

git branch <new-branch>
git checkout <new-branch>

This will create a new branch based on whatever local branch you were already in, i.e. that includes all the history of the original branch, which can be useful in building a hierarchy of dependent changes.

You may prefer to base your new branch on a remote branch such as the master branch of the central repository so you can integrate any new development. This is called 'tracking' and is recommended for most branches:

git branch --track <local-branch> <remote-branch>

For our KFoo example:

git branch --track new-bar-feature origin/master

=== Commit Your Changes ===

=== Push Your Changes ===

== Local Feature Development ==

This example workflow is for locally working on new features in unstable branch and pushing them to the central repository.

This workflow is only recommended for small features or where you are the only developer on a project.

== Remote Feature Development ==

This example workflow is for working on new features in a feature branch hosted on the central repository.

This workflow is recommended for larger features or where there are many developers on a project.

== Local Bug Fixing ==

This example workflow is for locally fixing bugs in both the stable and unstable branches and pushing them to the central repository.

In Git, stable branches are just regular branches that have special meaning to a project and a possibly a special naming scheme to distinguish them. For example, the KFoo app may have the following branches on the central repository:

origin/master
origin/feature/hot-new-stuff
origin/feature/cool-newer-stuff
origin/release/1.0
origin/release/1.1
origin/release/2.0

Making bug fixes to stable branches is thus fundamentally the same as working on a feature branch, but with the added step of needing to add the bug fix to the stable branch as well.

Two workflow's are described here, a basic workflow for small apps or where bug-fixes are infrequent, and an advanced workflow for larger apps or more frequent bug-fixes.

=== Basic Bug Fix Workflow ===

To make bug fixes on the 2.0 release you could simply checkout a local copy of the origin/release/2.0 branch and make you bug fixes there:

git branch --track bug-fix-2.0 origin/release/2.0
git checkout bug-fixes

However, switching between unstable and stable branches inside a single Git repository can lead to large rebuilds if the unstable branch has diverged too much from the stable branch. On a small app this overhead may be small enough to not be a problem in this case you would just use the feature workflow.

This workflow uses the [[http://techbase.kde.org/Development/Git/Configuration#Multiple_Work_Branches|git-new-workdir script]] to create separate work directories and builds for stable and unstable branches. This depends on you setting different up KDE Environments for the separate builds.

Development/Git/Simple Workflow

2011-06-05T12:40:11Z

Odysseus: /* Local Bug Fixing */

Development/Git/Simple Workflow

2011-06-05T12:39:07Z

Odysseus: /* Create a Work Branch */

Development/Git/Simple Workflow

2011-06-05T12:18:52Z

Odysseus:

Getting Started/Sources/Snapshots

2011-06-05T12:18:32Z

Odysseus:

{{Template:I18n/Language Navigation Bar|Getting Started/Sources/Snapshots}}
{{TutorialBrowser|

series=Getting Started|

name=Getting the Source using Snapshots|

next=[[../../Build|Building KDE]]|

reading=[[../../Sources/Anonymous_SVN|Anonymous SVN Quickstart Guide]]<br>[[Development/Tutorials/CMake |Introduction to CMake]]|
}}

If you are trying to checkout or clone a KDE source module, then there is a way to make the normally slow process of the initial checkout happen a lot quicker, thanks to automatically generated snapshots of the KDE source repository, which are stored in convenient archived form in the KDE FTP system. This page describes how to perform a checkout or clone using a module snapshot.

Keep in mind that these snapshots are '''real''' Subversion checkouts or Git Clones, containing all of the required Subversion or Git metadata. This procedure can in fact be the quickest way to checkout a module, thanks to the abundance of FTP mirrors.

{{note|For Subversion this procedure only works if the module you want has nightly snapshots generated (most do), and if you want the '''trunk''' version of the module. For Git snapshots are always generated and contain all unstable and stable branches.}}

== Git ==

The easiest way to obtain a Git snapshot is to use http://projects.kde.org/projects to find the project you want, then navigate to the Repository tab for that Project. Towards the top of the page is a small bar with buttons for 'Git', 'HTTP', 'SSH' and 'Tarball'. Click on the Tarball button, then copy the command displayed in the box. It will look something like:

wget -c http://anongit.kde.org/<project>/<project>-latest.tar.gz

Either run this command from your command line or use the URL in your favourite download tool. Once the download is complete unpack the archive, cd into the repository directory and run the following command to bring the snapshot up-to-date:

git pull --rebase

== Subversion ==

=== Get the snapshot ===

First go to [http://download.kde.org/ The KDE Mirror Redirector] and choose the best FTP server for your location. Usually this will be a server in your country/state. Click on the link for the FTP server and navigate to the {{path|snapshots}} directory. In this directory will be a large list of KDE modules which are archived.

You want to download the module with the name in the following format: '''kdemodule-svn.tar.bz2'''. Go ahead and save this archive to your hard disk somewhere. You'll need to be able to reach this location from the command line later.

{{note|It is important to get the module with the '''-svn''' in the file name. There are other types of snapshots also in the same directory for each module. But only modules with '''-svn''' contain the necessary information to allow for completing a checkout.}}

=== The Recipe ===

Now for the checkout, go ahead and open a terminal shell and perform the following steps:

cs # [[Getting_Started/Increased_Productivity_in_KDE4_with_Scripts/.bashrc|cs is not a typo]]
tar xvjf /path/to/kdemodule-svn.tar.bz2
cd kdemodule
svn revert -R . # This step restores the missing files.
svn up # This step updates the source to the latest code, and is optional.

=== Extra Tidbits ===

That's it! You've got a valid KDE module checkout now. Some things to keep in mind:

* Each module snapshot contains a special README.svn-nightly file containing information on how to use the snapshot. You've already performed the svn revert and update steps.
* The modules are already setup to update from the KDE anonymous Subversion repository (svn://anonsvn.kde.org/). If this is not correct for you (i.e. you're a developer), then you can use the svn switch command to fix the checkout as described in the README.svn-nightly file.
** Switch to the module source directory (cs <moduleName>)
** If you use Subversion over SSH, run '''svn switch --relocate svn://anonsvn.kde.org svn+ssh://<user>@svn.kde.org'''
** If you use Subversion over HTTPS, run '''svn switch --relocate svn://anonsvn.kde.org <nowiki>https://<user>@svn.kde.org</nowiki>'''
** (The way this works is that <tt>svn switch --relocate</tt> rewrites the Subversion metadata in the module, replacing the first substring (svn://anonsvn.kde.org) in the repository URL with the second substring (svn+ssh: or https:). This is done locally without any contact to the repository required.
* If you want to keep the module up to date in the future, just run svn up as you would for any other Subversion checkout. You do not have to continue downloading snapshots just to update the module, and to do so would be inefficient and slow.

[[Category:Build KDE]]

Development/Git/Simple Workflow

2011-06-05T11:47:15Z

Odysseus: Created page with '== Simple KDE Git Workflow == This Git Workflow is designed to be followed by a new Git user who needs a simple workflow for bug fixes and new features in a manner similar to th...'

Development/Git/Recipes

2011-06-05T09:30:49Z

Odysseus: /* Git Recipes */

== Git Recipes ==

Brief recipes for common use cases.

=== Cloning a Repository ===

To clone a local copy of a KDE Git repository, find the repository on http://projects.kde.org/projects, choose the project, choose the Repository tab and copy the git clone command displayed:

git clone git://anongit.kde.org/<repository-name>

Note this clone will be read-only and you will not be able to push from it.

Alternatively, if you have the standard [[Development/Git/Configuration|KDE Git configuration]] and know the name of the repository simply do:

git clone kde:<repository-name>

This will automatically set the repository up to have push access.

=== Working with existing remote branches ===

Remote branches are branches created on the main KDE repository. These may be a stable branch that you need to do bugfixes on, i.e. the 4.6 release, or a feature branch based on master.

To see what local and remote branches exist:
git branch -a

Create a local branch that tracks a remote branch:
git branch --track <local-branch> <remote-branch>
git checkout <local-branch>

When you want to add your commits to the local branch, first update your local to the current remote state, then push your commits:
git pull --rebase
git push origin <local-branch>:<remote-branch>

=== Working with stable branches ===

For kdelibs, kdepimlibs, kde-runtime, kate, konsole and kde-workspace, the remote stable branches are named as follows:

origin/KDE/4.6

For these modules, to set up a local stable branch to track the remote stable branch:

git branch --track KDE/4.6 origin/KDE/4.6
git checkout KDE/4.6

To then push changes to the remote stable branch:

git push origin KDE/4.6:KDE/4.6

In other projects the remote stable branches are named as follows:

origin/4.6

For these modules, to set up a local stable branch to track the remote stable branch:

git branch --track 4.6 origin/4.6
git checkout 4.6

To then push changes to the remote stable branch:

git push origin 4.6:4.6

=== Creating / Deleting Remote Branches ===

To create a new remote branch simply push your current branch to it:

git push origin <local-branch>:<remote-branch>

To delete a remote branch is a little obscure:

git push origin :<remote-branch>

=== Tracking Branches ===

To create a new branch that tracks an existing local or remote branch:

git branch --track <new-branch> <existing-branch>

To change the branch the current branch is tracking to a different local or remote branch:

git branch --set-upstream <existing-branch> <new-upstream-branch>

=== Cherry Picking ===

Cherry picking is a way to copy a single commit from any local or remote branch to your current local branch.

When cherry picking between stable and unstable branches, use the following form:

git cherry-pick -e -x <original-commit>

Note you can add ''any'' remote repository to your local clone if cherry-pick from.

;Common Options

'''-e''' will allow you to edit the commit message to add any extra details and to change the BUG/CCBUG/FIXED-IN messages.

'''-x''' will automatically add the original commit number to the end of the commit message to enable better tracing and to simplify merging. Only do this if the original commit was already published in a public repository, e.g. your are forward porting or back porting the patch.

'''-n''' will cherry-pick the changes but not commit them to the new branch. This is very useful if you need to do further work on a commit.

=== Interactive Rebasing ===

If you have many commits in a branch that you want to clean up before pushing to the central repository, then you can use interactive rebasing to merge, split, delete, re-order or edit them.

To work with all commits to a branch:

git rebase -i <parent-branch>

where <parent-branch> is the branch you want to rebase onto. This is usually the branch that you based the original local branch off or are remotely tracking, but can be any branch you want.

To work with just the last x commits you made to a branch:

git rebase -i HEAD^x

See http://book.git-scm.com/4_interactive_rebasing.html for full details.

=== Viewing What You've Changed ===

To see the difference between your tracked but unstaged changes and the current branch (including your not-yet-pushed commits)

git diff
git diff <filename>

To see the difference between your staged changes and the current branch (including your not-yet-pushed commits):

git diff --staged
git diff --staged <filename>

=== Stashing Changes ===

If you have changes you don't wish to commit but don't want to lose either while you do something else, you can temporarily 'stash' the changes away. This could be some frequently used debug code,or just some work in progress you need to move to another branch without committing. If the code is just WIP for the current branch we recommend using an interim commit instead.

The stash is a temporary store that holds a stack of uncommitted changes at a repository level. Commands given below work by default with the stash at the top of the stack, or you can optionally provide the stack reference.

To store your current changes at the top of the stash stack:

git stash <optional comment>

For example:

git stash "My debug code"

To see all your stashed items in the stash stack:

git stash list

This will show something like:

stash@{0}: WIP on master: 6ebd0e2... My debug code
stash@{1}: WIP on master: 9cc0589... My stashed changes

To see the details of an individual stash:

git stash show <optional stash ref>

To see the stash at the top of the stack:

git stash show

To see the second item from top:

git stash show stash@{1}

To restore a stash while keeping a copy in the stack:

git stash apply <optional stash ref>

To restore a stash and remove it from the stack:

git stash pop <optional stash ref>

To remove a single stash from the stack without applying it:

git stash drop <optional stash ref>

To clear out your entire stash stack:

git stash clear

For more details see:

http://www.kernel.org/pub/software/scm/git/docs/git-stash.html
http://book.git-scm.com/4_stashing.html

Getting Started/Sources

2011-06-04T10:17:09Z

Odysseus: /* KDE Software Modules */

== Source Repositories and Revision Control ==

KDE uses a central online repository to store our Source Code and to track changes made to the code. Currently, KDE is in the middle of migrating our main repository from [[/Subversion|Subversion (svn)]] to [[Development/Git|Git]], so some software modules currently live in Git while others are still only available from Subversion. This means you will need to become familiar with both systems.

== Obtaining The Source Code ==

There are three main ways of doing this:

* Directly access the KDE Source Repository using either Git or Subversion to copy the source code as it currently is with a full history of all changes. In Git this is know as Cloning the repository, in Subversion it is Checking-Out the code. This is most commonly done if you want to actively develop the code. The git repositories are available at [https://projects.kde.org/projects projects.kde.org].
* Download a tarball snapshot of the Source Repository to bootstrap a Git clone or Subversion checkout. This is a good option if you have a slow or unreliable internet connection. See the [[/Snapshots|Source Snapshots]] page for more details.
* Download a tarball snapshot of just the code as at a given time or release. This is most commonly done if you do not want to develop the code itself but just want to use it for a stable system installation, testing a release, or developing applications outside of the KDE SC.

Note that Checkout has a different meaning in Git than it does in Subversion.

== KDE Software Modules ==

Within the KDE Source Repository the code is organized in Projects and Modules. There are also a number of high-level groupings of the Modules.

=== Qt KDE ===

The '''Qt KDE''' module is a clone of the latest Qt release with patches made by KDE to fix specific issues before they are available in a Qt release.

The Qt KDE module is available from Git:
* https://projects.kde.org/projects/qt-kde

=== KDE Support ===

The '''KDE Support''' group is a set of tools and libraries that have been developed by KDE and that various KDE modules depend upon but are not themselves dependent on the KDE Development Platform. These libraries can thus be used by non-KDE applications without having to rely on KDE as well.

The KDE Support group is currently split between Git and SVN:
* https://projects.kde.org/projects/kdesupport
* http://websvn.kde.org/trunk/kdesupport/

=== KDE Software Compilation ===

The '''KDE Software Compilation''' (aka KDE SC) is an informal term covering all the KDE Software which is released together on the regular KDE Release Cycle.

The KDE SC group is currently split between Git and SVN:
* https://projects.kde.org/projects/kde
* http://websvn.kde.org/trunk/KDE/

==== KDE Development Platform ====

The '''KDE Development Platform''' group is defined as those KDE Modules that are required to run a KDE Application, i.e. the core libraries and runtime dependencies.

The KDE Development Platform is available from Git:

* [https://projects.kde.org/projects/kde/kdelibs KDE Libraries (kdelibs)]
* [https://projects.kde.org/projects/kde/kdepimlibs KDE PIM Libraries (kdepimlibs)]
* [https://projects.kde.org/projects/kde/kdebase/kde-runtime KDE Runtime (kde-runtime)]

==== KDE Base Applications ====

The '''KDE Base Applications''' group is defined as those basic applications that are required by the Workspace and other Applications, such as file management, terminal emulation and text editing.

The KDE Base Applications are available from Git:

* [https://projects.kde.org/projects/kde/kdebase/kde-baseapps KDE Base Applications (kde-baseapps)]
* [https://projects.kde.org/projects/kde/kdebase/konsole Konsole terminal emulator (konsole)]
* [https://projects.kde.org/projects/kde/kdebase/kate Kate text editor (kate)]

==== KDE Workspace ====

The '''KDE Workspace''' group (aka '''Plasma''') is defined as those KDE Modules that are needed to run a workspace, such as the Desktop or Netbook. This group is not needed to run a KDE Application under another workspace such as Gnome or Windows.

* [https://projects.kde.org/projects/kde/kdebase/kde-workspace KDE Workspace (kde-workspace)]

==== KDE Applications ====

The '''KDE Applications''' group is defined as those KDE modules built on the KDE Development Platform that are hosted by the KDE infrastructure and are released as part of the regular KDE Release Cycle, i.e. they are part of the KDE SC.

The KDE Applications group is currently split between Git and SVN:

* [http://websvn.kde.org/trunk/KDE/kdeaccessibility/ KDE Accessibility (kdeaccessibility)]
* [http://websvn.kde.org/trunk/KDE/kdeadmin/ KDE Admin (kdeadmin)]
* [http://websvn.kde.org/trunk/KDE/kdeartwork/ KDE Artwork (kdeartwork)]
* KDE Bindings (kdebindings)
** http://websvn.kde.org/trunk/KDE/kdebindings/
** https://projects.kde.org/projects/kde/kdebindings
* [https://projects.kde.org/projects/kde/kdeexamples KDE Examples (kdeexamples)]
* KDE Education (kdeedu)
** http://edu.kde.org/
** https://projects.kde.org/projects/kde/kdeedu
* KDE Games (kdegames)
** http://games.kde.org/
** http://websvn.kde.org/trunk/KDE/kdegames/
* [https://projects.kde.org/projects/kde/kdegraphics KDE Graphics (kdegraphics)]
* [http://websvn.kde.org/trunk/KDE/kdemultimedia/ KDE Multimedia (kdemultimedia) ]
* [http://websvn.kde.org/trunk/KDE/kdenetwork/ KDE Network (kdenetwork)]
* [https://projects.kde.org/projects/kde/kdeplasma-addons Plasma Addons (kdeplasma-addons)]
* KDE PIM / Kontact
** [https://projects.kde.org/projects/kde/kdepim KDE PIM(kdepim)]
** [https://projects.kde.org/projects/kde/kdepim-runtime KDE PIM Runtime (kdepim-runtime)]
* [http://websvn.kde.org/trunk/KDE/kdesdk/ KDE SDK (kdesdk)]
* [http://websvn.kde.org/trunk/KDE/kdetoys/ KDE Toys (kdetoys)]
* [http://websvn.kde.org/trunk/KDE/kdeutils/ KDE Utilities (kdeutils)]
* [http://websvn.kde.org/trunk/KDE/kdewebdev/ KDE Web Development (kdewebdev)]

=== KDE Extragear ===

The '''KDE Extragear''' group is defined as those applications built on the KDE Development Platform that are hosted by the KDE infrastructure and have a stable release but are not part of a KDE Module and are not released as part of the regular KDE Release Cycle, i.e. they are not part of the KDE SC.

The KDE Extragear group is currently split between Git and SVN:

* http://websvn.kde.org/trunk/extragear/
* https://projects.kde.org/projects/extragear

=== KDE Playground ===

The '''KDE Playground''' group is defined as those applications built on the KDE Development Platform that are hosted by the KDE infrastructure but have not yet had a stable release and may never be released.

The KDE Extragear group is currently split between Git and SVN:

* http://websvn.kde.org/trunk/playground/
* https://projects.kde.org/projects/playground

=== KDE Review ===

The '''KDE Review''' group is defined as those applications that are being reviewed for inclusion in a KDE Module or KDE Extragear, usually moving over from KDE Playground.

The KDE Review group is available from Git:

* [https://projects.kde.org/projects/kdereview KDE Review (kdereview)]

=== KDE Translations ===

* [http://websvn.kde.org/trunk/l10n-kde4/ KDE Translations (i18n)]

=== KDE Websites ===

KDE Websites (websites/www)

* http://websvn.kde.org/trunk/www/
* https://projects.kde.org/projects/websites

=== KOffice ===

KOffice (koffice) git, stable in svn

* http://websvn.kde.org/trunk/koffice/
* https://projects.kde.org/projects/koffice

=== Calligra ===

* [https://projects.kde.org/projects/calligra '''Calligra''' (calligra)]

Getting Started/Sources

2011-06-04T10:08:51Z

Odysseus: /* KDE Software Compilation */

== Source Repositories and Revision Control ==

KDE uses a central online repository to store our Source Code and to track changes made to the code. Currently, KDE is in the middle of migrating our main repository from [[/Subversion|Subversion (svn)]] to [[Development/Git|Git]], so some software modules currently live in Git while others are still only available from Subversion. This means you will need to become familiar with both systems.

== Obtaining The Source Code ==

There are three main ways of doing this:

* Directly access the KDE Source Repository using either Git or Subversion to copy the source code as it currently is with a full history of all changes. In Git this is know as Cloning the repository, in Subversion it is Checking-Out the code. This is most commonly done if you want to actively develop the code. The git repositories are available at [https://projects.kde.org/projects projects.kde.org].
* Download a tarball snapshot of the Source Repository to bootstrap a Git clone or Subversion checkout. This is a good option if you have a slow or unreliable internet connection. See the [[/Snapshots|Source Snapshots]] page for more details.
* Download a tarball snapshot of just the code as at a given time or release. This is most commonly done if you do not want to develop the code itself but just want to use it for a stable system installation, testing a release, or developing applications outside of the KDE SC.

Note that Checkout has a different meaning in Git than it does in Subversion.

== KDE Software Modules ==

Within the KDE Source Repository the code is organized in Projects and Modules. There are also a number of high-level groupings of the Modules.

=== Qt KDE ===

The '''Qt KDE''' module is a clone of the latest Qt release with patches made by KDE to fix specific issues before they are available in a Qt release.

The Qt KDE module is available from Git:
* https://projects.kde.org/projects/qt-kde

=== KDE Support ===

The '''KDE Support''' group is a set of tools and libraries that have been developed by KDE and that various KDE modules depend upon but are not themselves dependent on the KDE Development Platform. These libraries can thus be used by non-KDE applications without having to rely on KDE as well.

The KDE Support group is currently split between Git and SVN:
* https://projects.kde.org/projects/kdesupport
* http://websvn.kde.org/trunk/kdesupport/

=== KDE Software Compilation ===

The '''KDE Software Compilation''' (aka KDE SC) is an informal term covering all the KDE Software which is released together on the regular KDE Release Cycle.

The KDE SC group is currently split between Git and SVN:
* https://projects.kde.org/projects/kde
* http://websvn.kde.org/trunk/KDE/

==== KDE Development Platform ====

The '''KDE Development Platform''' group is defined as those KDE Modules that are required to run a KDE Application, i.e. the core libraries and runtime dependencies.

The KDE Development Platform is available from Git:

* [https://projects.kde.org/projects/kde/kdelibs KDE Libraries (kdelibs)]
* [https://projects.kde.org/projects/kde/kdepimlibs KDE PIM Libraries (kdepimlibs)]
* [https://projects.kde.org/projects/kde/kdebase/kde-runtime KDE Runtime (kde-runtime)]

==== KDE Base Applications ====

The '''KDE Base Applications''' group is defined as those basic applications that are required by the Workspace and other Applications, such as file management, terminal emulation and text editing.

The KDE Base Applications are available from Git:

* [https://projects.kde.org/projects/kde/kdebase/kde-baseapps KDE Base Applications (kde-baseapps)]
* [https://projects.kde.org/projects/kde/kdebase/konsole Konsole terminal emulator (konsole)]
* [https://projects.kde.org/projects/kde/kdebase/kate Kate text editor (kate)]

==== KDE Workspace ====

The '''KDE Workspace''' group (aka '''Plasma''') is defined as those KDE Modules that are needed to run a workspace, such as the Desktop or Netbook. This group is not needed to run a KDE Application under another workspace such as Gnome or Windows.

* [https://projects.kde.org/projects/kde/kdebase/kde-workspace KDE Workspace (kde-workspace)]

==== KDE Applications ====

The '''KDE Applications''' group is defined as those KDE modules built on the KDE Development Platform that are hosted by the KDE infrastructure and are released as part of the regular KDE Release Cycle, i.e. they are part of the KDE SC.

The KDE Applications group is currently split between Git and SVN:

* [http://websvn.kde.org/trunk/KDE/kdeaccessibility/ KDE Accessibility (kdeaccessibility)]
* [http://websvn.kde.org/trunk/KDE/kdeadmin/ KDE Admin (kdeadmin)]
* [http://websvn.kde.org/trunk/KDE/kdeartwork/ KDE Artwork (kdeartwork)]
* KDE Bindings (kdebindings)
** http://websvn.kde.org/trunk/KDE/kdebindings/
** https://projects.kde.org/projects/kde/kdebindings
* [https://projects.kde.org/projects/kde/kdeexamples KDE Examples (kdeexamples)]
* KDE Education (kdeedu)
** http://edu.kde.org/
** https://projects.kde.org/projects/kde/kdeedu
* KDE Games (kdegames)
** http://games.kde.org/
** http://websvn.kde.org/trunk/KDE/kdegames/
* [https://projects.kde.org/projects/kde/kdegraphics KDE Graphics (kdegraphics)]
* [http://websvn.kde.org/trunk/KDE/kdemultimedia/ KDE Multimedia (kdemultimedia) ]
* [http://websvn.kde.org/trunk/KDE/kdenetwork/ KDE Network (kdenetwork)]
* [https://projects.kde.org/projects/kde/kdeplasma-addons Plasma Addons (kdeplasma-addons)]
* KDE PIM / Kontact
** [https://projects.kde.org/projects/kde/kdepim KDE PIM(kdepim)]
** [https://projects.kde.org/projects/kde/kdepim-runtime KDE PIM Runtime (kdepim-runtime)]
* [http://websvn.kde.org/trunk/KDE/kdesdk/ KDE SDK (kdesdk)]
* [http://websvn.kde.org/trunk/KDE/kdetoys/ KDE Toys (kdetoys)]
* [http://websvn.kde.org/trunk/KDE/kdeutils/ KDE Utilities (kdeutils)]
* [http://websvn.kde.org/trunk/KDE/kdewebdev/ KDE Web Development (kdewebdev)]

=== KDE Extragear ===

The '''KDE Extragear''' group is defined as those applications built on the KDE Development Platform that are hosted by the KDE infrastructure and have a stable release but are not part of a KDE Module and are not released as part of the regular KDE Release Cycle, i.e. they are not part of the KDE SC.

* KDE Extragear (extragear) Git/svn

=== KDE Playground ===

The '''KDE Playground''' group is defined as those applications built on the KDE Development Platform that are hosted by the KDE infrastructure but have not yet had a stable release and may never be released.

* KDE Playground (playground) git/svn

=== KDE Review ===

The '''KDE Review''' group is defined as those applications that are being reviewed for inclusion in a KDE Module or KDE Extragear, usually moving over from KDE Playground.

=== KDE Translations ===

* KDE Translations (i18n) svn

=== KDE Websites ===

* KDE Websites (websites/www) git/svn

=== KOffice ===

* KOffice (koffice) git, stable in svn

=== Calligra ===

* '''Calligra''' (calligra) git

Getting Started/Sources

2011-06-04T10:06:58Z

Odysseus: /* KDE Applications */

== Source Repositories and Revision Control ==

KDE uses a central online repository to store our Source Code and to track changes made to the code. Currently, KDE is in the middle of migrating our main repository from [[/Subversion|Subversion (svn)]] to [[Development/Git|Git]], so some software modules currently live in Git while others are still only available from Subversion. This means you will need to become familiar with both systems.

== Obtaining The Source Code ==

There are three main ways of doing this:

* Directly access the KDE Source Repository using either Git or Subversion to copy the source code as it currently is with a full history of all changes. In Git this is know as Cloning the repository, in Subversion it is Checking-Out the code. This is most commonly done if you want to actively develop the code. The git repositories are available at [https://projects.kde.org/projects projects.kde.org].
* Download a tarball snapshot of the Source Repository to bootstrap a Git clone or Subversion checkout. This is a good option if you have a slow or unreliable internet connection. See the [[/Snapshots|Source Snapshots]] page for more details.
* Download a tarball snapshot of just the code as at a given time or release. This is most commonly done if you do not want to develop the code itself but just want to use it for a stable system installation, testing a release, or developing applications outside of the KDE SC.

Note that Checkout has a different meaning in Git than it does in Subversion.

== KDE Software Modules ==

Within the KDE Source Repository the code is organized in Projects and Modules. There are also a number of high-level groupings of the Modules.

=== Qt KDE ===

The '''Qt KDE''' module is a clone of the latest Qt release with patches made by KDE to fix specific issues before they are available in a Qt release.

The Qt KDE module is available from Git:
* https://projects.kde.org/projects/qt-kde

=== KDE Support ===

The '''KDE Support''' group is a set of tools and libraries that have been developed by KDE and that various KDE modules depend upon but are not themselves dependent on the KDE Development Platform. These libraries can thus be used by non-KDE applications without having to rely on KDE as well.

The KDE Support group is currently split between Git and SVN:
* https://projects.kde.org/projects/kdesupport
* http://websvn.kde.org/trunk/kdesupport/

=== KDE Software Compilation ===

The '''KDE Software Compilation''' (aka KDE SC) is an informal term covering all the KDE Software which is released together on the regular KDE Release Cycle.

The KDE SC group is currently split between Git and SVN:
* https://projects.kde.org/projects/kde
* http://websvn.kde.org/trunk/KDE/

==== KDE Development Platform ====

The '''KDE Development Platform''' group is defined as those KDE Modules that are required to run a KDE Application, i.e. the core libraries and runtime dependencies.

The KDE Development Platform is available from Git:

* [https://projects.kde.org/projects/kde/kdelibs KDE Libraries (kdelibs)]
* [https://projects.kde.org/projects/kde/kdepimlibs KDE PIM Libraries (kdepimlibs)]
* [https://projects.kde.org/projects/kde/kdebase/kde-runtime KDE Runtime (kde-runtime)]

==== KDE Base Applications ====

The '''KDE Base Applications''' group is defined as those basic applications that are required by the Workspace and other Applications, such as file management, terminal emulation and text editing.

The KDE Base Applications are available from Git:

* [https://projects.kde.org/projects/kde/kdebase/kde-baseapps KDE Base Applications (kde-baseapps)]
* [https://projects.kde.org/projects/kde/kdebase/konsole Konsole terminal emulator (konsole)]
* [https://projects.kde.org/projects/kde/kdebase/kate Kate text editor (kate)]

==== KDE Workspace ====

The '''KDE Workspace''' group (aka '''Plasma''') is defined as those KDE Modules that are needed to run a workspace, such as the Desktop or Netbook. This group is not needed to run a KDE Application under another workspace such as Gnome or Windows.

* [https://projects.kde.org/projects/kde/kdebase/kde-workspace KDE Workspace (kde-workspace)]

==== KDE Applications ====

The '''KDE Applications''' group is defined as those KDE modules built on the KDE Development Platform that are hosted by the KDE infrastructure and are released as part of the regular KDE Release Cycle, i.e. they are part of the KDE SC.

* [http://websvn.kde.org/trunk/KDE/kdeaccessibility/ KDE Accessibility (kdeaccessibility)]
* [http://websvn.kde.org/trunk/KDE/kdeadmin/ KDE Admin (kdeadmin)]
* [http://websvn.kde.org/trunk/KDE/kdeartwork/ KDE Artwork (kdeartwork)]
* KDE Bindings (kdebindings)
** http://websvn.kde.org/trunk/KDE/kdebindings/
** https://projects.kde.org/projects/kde/kdebindings
* [https://projects.kde.org/projects/kde/kdeexamples KDE Examples (kdeexamples)]
* KDE Education (kdeedu)
** http://edu.kde.org/
** https://projects.kde.org/projects/kde/kdeedu
* KDE Games (kdegames)
** http://games.kde.org/
** http://websvn.kde.org/trunk/KDE/kdegames/
* [https://projects.kde.org/projects/kde/kdegraphics KDE Graphics (kdegraphics)]
* [http://websvn.kde.org/trunk/KDE/kdemultimedia/ KDE Multimedia (kdemultimedia) ]
* [http://websvn.kde.org/trunk/KDE/kdenetwork/ KDE Network (kdenetwork)]
* [https://projects.kde.org/projects/kde/kdeplasma-addons Plasma Addons (kdeplasma-addons)]
* KDE PIM / Kontact
** [https://projects.kde.org/projects/kde/kdepim KDE PIM(kdepim)]
** [https://projects.kde.org/projects/kde/kdepim-runtime KDE PIM Runtime (kdepim-runtime)]
* [http://websvn.kde.org/trunk/KDE/kdesdk/ KDE SDK (kdesdk)]
* [http://websvn.kde.org/trunk/KDE/kdetoys/ KDE Toys (kdetoys)]
* [http://websvn.kde.org/trunk/KDE/kdeutils/ KDE Utilities (kdeutils)]
* [http://websvn.kde.org/trunk/KDE/kdewebdev/ KDE Web Development (kdewebdev)]

=== KDE Extragear ===

The '''KDE Extragear''' group is defined as those applications built on the KDE Development Platform that are hosted by the KDE infrastructure and have a stable release but are not part of a KDE Module and are not released as part of the regular KDE Release Cycle, i.e. they are not part of the KDE SC.

* KDE Extragear (extragear) Git/svn

=== KDE Playground ===

The '''KDE Playground''' group is defined as those applications built on the KDE Development Platform that are hosted by the KDE infrastructure but have not yet had a stable release and may never be released.

* KDE Playground (playground) git/svn

=== KDE Review ===

The '''KDE Review''' group is defined as those applications that are being reviewed for inclusion in a KDE Module or KDE Extragear, usually moving over from KDE Playground.

=== KDE Translations ===

* KDE Translations (i18n) svn

=== KDE Websites ===

* KDE Websites (websites/www) git/svn

=== KOffice ===

* KOffice (koffice) git, stable in svn

=== Calligra ===

* '''Calligra''' (calligra) git

Getting Started/Sources

2011-06-04T09:55:48Z

Odysseus: /* KDE Base Applications */

== Source Repositories and Revision Control ==

KDE uses a central online repository to store our Source Code and to track changes made to the code. Currently, KDE is in the middle of migrating our main repository from [[/Subversion|Subversion (svn)]] to [[Development/Git|Git]], so some software modules currently live in Git while others are still only available from Subversion. This means you will need to become familiar with both systems.

== Obtaining The Source Code ==

There are three main ways of doing this:

* Directly access the KDE Source Repository using either Git or Subversion to copy the source code as it currently is with a full history of all changes. In Git this is know as Cloning the repository, in Subversion it is Checking-Out the code. This is most commonly done if you want to actively develop the code. The git repositories are available at [https://projects.kde.org/projects projects.kde.org].
* Download a tarball snapshot of the Source Repository to bootstrap a Git clone or Subversion checkout. This is a good option if you have a slow or unreliable internet connection. See the [[/Snapshots|Source Snapshots]] page for more details.
* Download a tarball snapshot of just the code as at a given time or release. This is most commonly done if you do not want to develop the code itself but just want to use it for a stable system installation, testing a release, or developing applications outside of the KDE SC.

Note that Checkout has a different meaning in Git than it does in Subversion.

== KDE Software Modules ==

Within the KDE Source Repository the code is organized in Projects and Modules. There are also a number of high-level groupings of the Modules.

=== Qt KDE ===

The '''Qt KDE''' module is a clone of the latest Qt release with patches made by KDE to fix specific issues before they are available in a Qt release.

The Qt KDE module is available from Git:
* https://projects.kde.org/projects/qt-kde

=== KDE Support ===

The '''KDE Support''' group is a set of tools and libraries that have been developed by KDE and that various KDE modules depend upon but are not themselves dependent on the KDE Development Platform. These libraries can thus be used by non-KDE applications without having to rely on KDE as well.

The KDE Support group is currently split between Git and SVN:
* https://projects.kde.org/projects/kdesupport
* http://websvn.kde.org/trunk/kdesupport/

=== KDE Software Compilation ===

The '''KDE Software Compilation''' (aka KDE SC) is an informal term covering all the KDE Software which is released together on the regular KDE Release Cycle.

The KDE SC group is currently split between Git and SVN:
* https://projects.kde.org/projects/kde
* http://websvn.kde.org/trunk/KDE/

==== KDE Development Platform ====

The '''KDE Development Platform''' group is defined as those KDE Modules that are required to run a KDE Application, i.e. the core libraries and runtime dependencies.

The KDE Development Platform is available from Git:

* [https://projects.kde.org/projects/kde/kdelibs KDE Libraries (kdelibs)]
* [https://projects.kde.org/projects/kde/kdepimlibs KDE PIM Libraries (kdepimlibs)]
* [https://projects.kde.org/projects/kde/kdebase/kde-runtime KDE Runtime (kde-runtime)]

==== KDE Base Applications ====

The '''KDE Base Applications''' group is defined as those basic applications that are required by the Workspace and other Applications, such as file management, terminal emulation and text editing.

The KDE Base Applications are available from Git:

* [https://projects.kde.org/projects/kde/kdebase/kde-baseapps KDE Base Applications (kde-baseapps)]
* [https://projects.kde.org/projects/kde/kdebase/konsole Konsole terminal emulator (konsole)]
* [https://projects.kde.org/projects/kde/kdebase/kate Kate text editor (kate)]

==== KDE Workspace ====

The '''KDE Workspace''' group (aka '''Plasma''') is defined as those KDE Modules that are needed to run a workspace, such as the Desktop or Netbook. This group is not needed to run a KDE Application under another workspace such as Gnome or Windows.

* [https://projects.kde.org/projects/kde/kdebase/kde-workspace KDE Workspace (kde-workspace)]

==== KDE Applications ====

The '''KDE Applications''' group is defined as those KDE modules built on the KDE Development Platform that are hosted by the KDE infrastructure and are released as part of the regular KDE Release Cycle, i.e. they are part of the KDE SC.

* KDE Accessibility (kdeaccessibility) svn
* KDE Admin (kdeadmin) svn
* KDE Artwork (kdeartwork) svn
* KDE Bindings (kdebindings) git/svn
* KDE Examples (kdeexamples) git
* KDE Education (kdeedu) git
* KDE Games (kdegames) svn
* KDE Graphics (kdegraphics) git
* KDE Network (kdenetwork) svn
* KDE Multimedia (kdemultimedia) svn
* Plasma Addons (kdeplasma-addons) git
* KDE PIM Runtime (kdepim-runtime) Git
* '''Kontact''' and Kontact Touch as part of KDE PIM (kdepim) Git
* KDE SDK (kdesdk) svn
* KDE Toys (kdetoys) svn
* KDE Utilities (kdeutils) svn
* KDE Web Development (kdewebdev) svn

=== KDE Extragear ===

The '''KDE Extragear''' group is defined as those applications built on the KDE Development Platform that are hosted by the KDE infrastructure and have a stable release but are not part of a KDE Module and are not released as part of the regular KDE Release Cycle, i.e. they are not part of the KDE SC.

* KDE Extragear (extragear) Git/svn

=== KDE Playground ===

The '''KDE Playground''' group is defined as those applications built on the KDE Development Platform that are hosted by the KDE infrastructure but have not yet had a stable release and may never be released.

* KDE Playground (playground) git/svn

=== KDE Review ===

The '''KDE Review''' group is defined as those applications that are being reviewed for inclusion in a KDE Module or KDE Extragear, usually moving over from KDE Playground.

=== KDE Translations ===

* KDE Translations (i18n) svn

=== KDE Websites ===

* KDE Websites (websites/www) git/svn

=== KOffice ===

* KOffice (koffice) git, stable in svn

=== Calligra ===

* '''Calligra''' (calligra) git

Getting Started/Sources

2011-06-04T09:55:05Z

Odysseus: /* KDE Workspace */

== Source Repositories and Revision Control ==

KDE uses a central online repository to store our Source Code and to track changes made to the code. Currently, KDE is in the middle of migrating our main repository from [[/Subversion|Subversion (svn)]] to [[Development/Git|Git]], so some software modules currently live in Git while others are still only available from Subversion. This means you will need to become familiar with both systems.

== Obtaining The Source Code ==

There are three main ways of doing this:

* Directly access the KDE Source Repository using either Git or Subversion to copy the source code as it currently is with a full history of all changes. In Git this is know as Cloning the repository, in Subversion it is Checking-Out the code. This is most commonly done if you want to actively develop the code. The git repositories are available at [https://projects.kde.org/projects projects.kde.org].
* Download a tarball snapshot of the Source Repository to bootstrap a Git clone or Subversion checkout. This is a good option if you have a slow or unreliable internet connection. See the [[/Snapshots|Source Snapshots]] page for more details.
* Download a tarball snapshot of just the code as at a given time or release. This is most commonly done if you do not want to develop the code itself but just want to use it for a stable system installation, testing a release, or developing applications outside of the KDE SC.

Note that Checkout has a different meaning in Git than it does in Subversion.

== KDE Software Modules ==

Within the KDE Source Repository the code is organized in Projects and Modules. There are also a number of high-level groupings of the Modules.

=== Qt KDE ===

The '''Qt KDE''' module is a clone of the latest Qt release with patches made by KDE to fix specific issues before they are available in a Qt release.

The Qt KDE module is available from Git:
* https://projects.kde.org/projects/qt-kde

=== KDE Support ===

The '''KDE Support''' group is a set of tools and libraries that have been developed by KDE and that various KDE modules depend upon but are not themselves dependent on the KDE Development Platform. These libraries can thus be used by non-KDE applications without having to rely on KDE as well.

The KDE Support group is currently split between Git and SVN:
* https://projects.kde.org/projects/kdesupport
* http://websvn.kde.org/trunk/kdesupport/

=== KDE Software Compilation ===

The '''KDE Software Compilation''' (aka KDE SC) is an informal term covering all the KDE Software which is released together on the regular KDE Release Cycle.

The KDE SC group is currently split between Git and SVN:
* https://projects.kde.org/projects/kde
* http://websvn.kde.org/trunk/KDE/

==== KDE Development Platform ====

The '''KDE Development Platform''' group is defined as those KDE Modules that are required to run a KDE Application, i.e. the core libraries and runtime dependencies.

The KDE Development Platform is available from Git:

* [https://projects.kde.org/projects/kde/kdelibs KDE Libraries (kdelibs)]
* [https://projects.kde.org/projects/kde/kdepimlibs KDE PIM Libraries (kdepimlibs)]
* [https://projects.kde.org/projects/kde/kdebase/kde-runtime KDE Runtime (kde-runtime)]

=== KDE Base Applications ===

The '''KDE Base Applications''' group is defined as those basic applications that are required by the Workspace and other Applications, such as file management, terminal emulation and text editing.

The KDE Base Applications are available from Git:

* [https://projects.kde.org/projects/kde/kdebase/kde-baseapps KDE Base Applications (kde-baseapps)]
* [https://projects.kde.org/projects/kde/kdebase/konsole Konsole terminal emulator (konsole)]
* [https://projects.kde.org/projects/kde/kdebase/kate Kate text editor (kate)]

==== KDE Workspace ====

The '''KDE Workspace''' group (aka '''Plasma''') is defined as those KDE Modules that are needed to run a workspace, such as the Desktop or Netbook. This group is not needed to run a KDE Application under another workspace such as Gnome or Windows.

* [https://projects.kde.org/projects/kde/kdebase/kde-workspace KDE Workspace (kde-workspace)]

==== KDE Applications ====

The '''KDE Applications''' group is defined as those KDE modules built on the KDE Development Platform that are hosted by the KDE infrastructure and are released as part of the regular KDE Release Cycle, i.e. they are part of the KDE SC.

* KDE Accessibility (kdeaccessibility) svn
* KDE Admin (kdeadmin) svn
* KDE Artwork (kdeartwork) svn
* KDE Bindings (kdebindings) git/svn
* KDE Examples (kdeexamples) git
* KDE Education (kdeedu) git
* KDE Games (kdegames) svn
* KDE Graphics (kdegraphics) git
* KDE Network (kdenetwork) svn
* KDE Multimedia (kdemultimedia) svn
* Plasma Addons (kdeplasma-addons) git
* KDE PIM Runtime (kdepim-runtime) Git
* '''Kontact''' and Kontact Touch as part of KDE PIM (kdepim) Git
* KDE SDK (kdesdk) svn
* KDE Toys (kdetoys) svn
* KDE Utilities (kdeutils) svn
* KDE Web Development (kdewebdev) svn

=== KDE Extragear ===

The '''KDE Extragear''' group is defined as those applications built on the KDE Development Platform that are hosted by the KDE infrastructure and have a stable release but are not part of a KDE Module and are not released as part of the regular KDE Release Cycle, i.e. they are not part of the KDE SC.

* KDE Extragear (extragear) Git/svn

=== KDE Playground ===

The '''KDE Playground''' group is defined as those applications built on the KDE Development Platform that are hosted by the KDE infrastructure but have not yet had a stable release and may never be released.

* KDE Playground (playground) git/svn

=== KDE Review ===

The '''KDE Review''' group is defined as those applications that are being reviewed for inclusion in a KDE Module or KDE Extragear, usually moving over from KDE Playground.

=== KDE Translations ===

* KDE Translations (i18n) svn

=== KDE Websites ===

* KDE Websites (websites/www) git/svn

=== KOffice ===

* KOffice (koffice) git, stable in svn

=== Calligra ===

* '''Calligra''' (calligra) git

Getting Started/Sources

2011-06-04T09:54:34Z

Odysseus: /* KDE Development Platform */

== Source Repositories and Revision Control ==

KDE uses a central online repository to store our Source Code and to track changes made to the code. Currently, KDE is in the middle of migrating our main repository from [[/Subversion|Subversion (svn)]] to [[Development/Git|Git]], so some software modules currently live in Git while others are still only available from Subversion. This means you will need to become familiar with both systems.

== Obtaining The Source Code ==

There are three main ways of doing this:

* Directly access the KDE Source Repository using either Git or Subversion to copy the source code as it currently is with a full history of all changes. In Git this is know as Cloning the repository, in Subversion it is Checking-Out the code. This is most commonly done if you want to actively develop the code. The git repositories are available at [https://projects.kde.org/projects projects.kde.org].
* Download a tarball snapshot of the Source Repository to bootstrap a Git clone or Subversion checkout. This is a good option if you have a slow or unreliable internet connection. See the [[/Snapshots|Source Snapshots]] page for more details.
* Download a tarball snapshot of just the code as at a given time or release. This is most commonly done if you do not want to develop the code itself but just want to use it for a stable system installation, testing a release, or developing applications outside of the KDE SC.

Note that Checkout has a different meaning in Git than it does in Subversion.

== KDE Software Modules ==

Within the KDE Source Repository the code is organized in Projects and Modules. There are also a number of high-level groupings of the Modules.

=== Qt KDE ===

The '''Qt KDE''' module is a clone of the latest Qt release with patches made by KDE to fix specific issues before they are available in a Qt release.

The Qt KDE module is available from Git:
* https://projects.kde.org/projects/qt-kde

=== KDE Support ===

The '''KDE Support''' group is a set of tools and libraries that have been developed by KDE and that various KDE modules depend upon but are not themselves dependent on the KDE Development Platform. These libraries can thus be used by non-KDE applications without having to rely on KDE as well.

The KDE Support group is currently split between Git and SVN:
* https://projects.kde.org/projects/kdesupport
* http://websvn.kde.org/trunk/kdesupport/

=== KDE Software Compilation ===

The '''KDE Software Compilation''' (aka KDE SC) is an informal term covering all the KDE Software which is released together on the regular KDE Release Cycle.

The KDE SC group is currently split between Git and SVN:
* https://projects.kde.org/projects/kde
* http://websvn.kde.org/trunk/KDE/

==== KDE Development Platform ====

The '''KDE Development Platform''' group is defined as those KDE Modules that are required to run a KDE Application, i.e. the core libraries and runtime dependencies.

The KDE Development Platform is available from Git:

* [https://projects.kde.org/projects/kde/kdelibs KDE Libraries (kdelibs)]
* [https://projects.kde.org/projects/kde/kdepimlibs KDE PIM Libraries (kdepimlibs)]
* [https://projects.kde.org/projects/kde/kdebase/kde-runtime KDE Runtime (kde-runtime)]

=== KDE Base Applications ===

The '''KDE Base Applications''' group is defined as those basic applications that are required by the Workspace and other Applications, such as file management, terminal emulation and text editing.

The KDE Base Applications are available from Git:

* [https://projects.kde.org/projects/kde/kdebase/kde-baseapps KDE Base Applications (kde-baseapps)]
* [https://projects.kde.org/projects/kde/kdebase/konsole Konsole terminal emulator (konsole)]
* [https://projects.kde.org/projects/kde/kdebase/kate Kate text editor (kate)]

==== KDE Workspace ====

The '''KDE Workspace''' group (aka '''Plasma''') is defined as those KDE Modules that are needed to run a workspace, such as the Desktop or Netbook. This group is not needed to run a KDE Application under another workspace such as Gnome or Windows.

* KDE Workspace (kde-workspace) Git
* KDE Base Applications (kde-baseapps) Git

==== KDE Applications ====

The '''KDE Applications''' group is defined as those KDE modules built on the KDE Development Platform that are hosted by the KDE infrastructure and are released as part of the regular KDE Release Cycle, i.e. they are part of the KDE SC.

* KDE Accessibility (kdeaccessibility) svn
* KDE Admin (kdeadmin) svn
* KDE Artwork (kdeartwork) svn
* KDE Bindings (kdebindings) git/svn
* KDE Examples (kdeexamples) git
* KDE Education (kdeedu) git
* KDE Games (kdegames) svn
* KDE Graphics (kdegraphics) git
* KDE Network (kdenetwork) svn
* KDE Multimedia (kdemultimedia) svn
* Plasma Addons (kdeplasma-addons) git
* KDE PIM Runtime (kdepim-runtime) Git
* '''Kontact''' and Kontact Touch as part of KDE PIM (kdepim) Git
* KDE SDK (kdesdk) svn
* KDE Toys (kdetoys) svn
* KDE Utilities (kdeutils) svn
* KDE Web Development (kdewebdev) svn

=== KDE Extragear ===

The '''KDE Extragear''' group is defined as those applications built on the KDE Development Platform that are hosted by the KDE infrastructure and have a stable release but are not part of a KDE Module and are not released as part of the regular KDE Release Cycle, i.e. they are not part of the KDE SC.

* KDE Extragear (extragear) Git/svn

=== KDE Playground ===

The '''KDE Playground''' group is defined as those applications built on the KDE Development Platform that are hosted by the KDE infrastructure but have not yet had a stable release and may never be released.

* KDE Playground (playground) git/svn

=== KDE Review ===

The '''KDE Review''' group is defined as those applications that are being reviewed for inclusion in a KDE Module or KDE Extragear, usually moving over from KDE Playground.

=== KDE Translations ===

* KDE Translations (i18n) svn

=== KDE Websites ===

* KDE Websites (websites/www) git/svn

=== KOffice ===

* KOffice (koffice) git, stable in svn

=== Calligra ===

* '''Calligra''' (calligra) git

Getting Started/Sources

2011-06-04T09:45:07Z

Odysseus: /* KDE Software Modules */

== Source Repositories and Revision Control ==

KDE uses a central online repository to store our Source Code and to track changes made to the code. Currently, KDE is in the middle of migrating our main repository from [[/Subversion|Subversion (svn)]] to [[Development/Git|Git]], so some software modules currently live in Git while others are still only available from Subversion. This means you will need to become familiar with both systems.

== Obtaining The Source Code ==

There are three main ways of doing this:

* Directly access the KDE Source Repository using either Git or Subversion to copy the source code as it currently is with a full history of all changes. In Git this is know as Cloning the repository, in Subversion it is Checking-Out the code. This is most commonly done if you want to actively develop the code. The git repositories are available at [https://projects.kde.org/projects projects.kde.org].
* Download a tarball snapshot of the Source Repository to bootstrap a Git clone or Subversion checkout. This is a good option if you have a slow or unreliable internet connection. See the [[/Snapshots|Source Snapshots]] page for more details.
* Download a tarball snapshot of just the code as at a given time or release. This is most commonly done if you do not want to develop the code itself but just want to use it for a stable system installation, testing a release, or developing applications outside of the KDE SC.

Note that Checkout has a different meaning in Git than it does in Subversion.

== KDE Software Modules ==

Within the KDE Source Repository the code is organized in Projects and Modules. There are also a number of high-level groupings of the Modules.

=== Qt KDE ===

The '''Qt KDE''' module is a clone of the latest Qt release with patches made by KDE to fix specific issues before they are available in a Qt release.

The Qt KDE module is available from Git:
* https://projects.kde.org/projects/qt-kde

=== KDE Support ===

The '''KDE Support''' group is a set of tools and libraries that have been developed by KDE and that various KDE modules depend upon but are not themselves dependent on the KDE Development Platform. These libraries can thus be used by non-KDE applications without having to rely on KDE as well.

The KDE Support group is currently split between Git and SVN:
* https://projects.kde.org/projects/kdesupport
* http://websvn.kde.org/trunk/kdesupport/

=== KDE Software Compilation ===

The '''KDE Software Compilation''' (aka KDE SC) is an informal term covering all the KDE Software which is released together on the regular KDE Release Cycle.

The KDE SC group is currently split between Git and SVN:
* https://projects.kde.org/projects/kde
* http://websvn.kde.org/trunk/KDE/

==== KDE Development Platform ====

The '''KDE Development Platform''' group is defined as those KDE Modules that are required to run a KDE Application, i.e. the core libraries and runtime dependencies.

The KDE Development Platform is available from Git:

* [https://projects.kde.org/projects/kde/kdelibs KDE Libraries (kdelibs)]
* [https://projects.kde.org/projects/kde/kdepimlibs KDE PIM Libraries (kdepimlibs)]
* [https://projects.kde.org/projects/kde/kdebase/kde-runtime KDE Runtime (kde-runtime)]

==== KDE Workspace ====

The '''KDE Workspace''' group (aka '''Plasma''') is defined as those KDE Modules that are needed to run a workspace, such as the Desktop or Netbook. This group is not needed to run a KDE Application under another workspace such as Gnome or Windows.

* KDE Workspace (kde-workspace) Git
* KDE Base Applications (kde-baseapps) Git

==== KDE Applications ====

The '''KDE Applications''' group is defined as those KDE modules built on the KDE Development Platform that are hosted by the KDE infrastructure and are released as part of the regular KDE Release Cycle, i.e. they are part of the KDE SC.

* KDE Accessibility (kdeaccessibility) svn
* KDE Admin (kdeadmin) svn
* KDE Artwork (kdeartwork) svn
* KDE Bindings (kdebindings) git/svn
* KDE Examples (kdeexamples) git
* KDE Education (kdeedu) git
* KDE Games (kdegames) svn
* KDE Graphics (kdegraphics) git
* KDE Network (kdenetwork) svn
* KDE Multimedia (kdemultimedia) svn
* Plasma Addons (kdeplasma-addons) git
* KDE PIM Runtime (kdepim-runtime) Git
* '''Kontact''' and Kontact Touch as part of KDE PIM (kdepim) Git
* KDE SDK (kdesdk) svn
* KDE Toys (kdetoys) svn
* KDE Utilities (kdeutils) svn
* KDE Web Development (kdewebdev) svn

=== KDE Extragear ===

The '''KDE Extragear''' group is defined as those applications built on the KDE Development Platform that are hosted by the KDE infrastructure and have a stable release but are not part of a KDE Module and are not released as part of the regular KDE Release Cycle, i.e. they are not part of the KDE SC.

* KDE Extragear (extragear) Git/svn

=== KDE Playground ===

The '''KDE Playground''' group is defined as those applications built on the KDE Development Platform that are hosted by the KDE infrastructure but have not yet had a stable release and may never be released.

* KDE Playground (playground) git/svn

=== KDE Review ===

The '''KDE Review''' group is defined as those applications that are being reviewed for inclusion in a KDE Module or KDE Extragear, usually moving over from KDE Playground.

=== KDE Translations ===

* KDE Translations (i18n) svn

=== KDE Websites ===

* KDE Websites (websites/www) git/svn

=== KOffice ===

* KOffice (koffice) git, stable in svn

=== Calligra ===

* '''Calligra''' (calligra) git

Getting Started/Sources

2011-06-04T09:35:28Z

Odysseus: /* Qt KDE */

Getting Started

2011-06-04T09:28:55Z

Odysseus: /* Introduction */

{{warning|These pages are currently being completely re-written to reflect the new KDE infrastructure and may not be in a consistent state. Information and commands on some page may no longer be valid and should be used with care.}}

{{Template:I18n/Language Navigation Bar|Getting_Started}}

== Introduction ==
There are many different ways to become involved in the KDE Community, ranging all the way from a simply using our software through to being a core platform developer.

You can find more general information on getting involved in KDE at the following links:
* [http://kde.org/community/getinvolved/ Getting Involved in KDE]
* [[Contribute|Contribute to KDE]]

This section of KDE TechBase is designed to help get you started in participating in the technical side of the KDE community. It will explain to you how KDE Software is structured and built, and how you can participate by building KDE for yourself.

{{note|'''Quickstart:''' If you are impatient to get started without understanding what you are doing then you can skip straight to using a [[/Build#Scripted_Builds|Build Script]], but it is strongly recommended you read this documentation first.}}

== Using KDE Software ==
If you just want to use stable KDE software for your everyday computing needs, then you do not need to build KDE Software for yourself. You should instead use the software installer provided by your Linux distribution to install KDE package.

The best place to learn how to do this is through your distributions normal support channels, although you may find some useful information on the following pages:
* [http://www.kde.org/download/distributions.php Distributions shipping KDE]
* [[/Build/Distributions|Install KDE Software on Linux and BSD Distributions]]
* [[Projects/KDE_on_Windows/Installation|Install KDE Software on Windows]]
* Mac OS X does not currently have an installer available for KDE Software, but you can simplify building it by using [http://mac.kde.org/?id=build MacPorts or Fink]

== Getting Help ==
If you are looking for help in using the KDE Workspace or KDE Applications then please visit the [http://userbase.kde.org/ KDE UserBase].

If you have any questions or problems with building or developing KDE Software please feel free to [[Development/Getting_Help|ask for help]]. However, be patient while waiting for a response, and try to work through the problem yourself, we aren't going to do it ''all'' for you. Working your way through and understanding why something doesn't work is a good way to learn how to do things the right way.

== Building and Running KDE Software From Source ==

There are several possible ways to build and install KDE software and the method you choose depends on what you want to do with the software. In particular if you are only wanting to build and develop a single application you may not need to build the entire KDE Development Platform to do so. You can read more about this on the [[Getting_Started/Build/Methods|Build Methods page]].

The following sections explain the steps you need to understand and give the instructions you need to follow to successfully build KDE Software from source:

* [[/Sources|How the KDE Source Code is structured]]
* [[/Build|How to Build and Install the software]]
* [[/Run|How to Run the software]]

== Development Model ==
TODO: General introduction to the dev model, release cycles, etc.

* [[Schedules/Release_Schedules_Guide|The KDE Release Schedule]]
* [[Development/Software_Engineering_Framework|The KDE Software Engineering Framwork]]
* [[Policies|KDE Development Policies and Procedures to follow]]
* [[Policies/Application_Lifecycle|The development lifecycle for a new application]]

== Development Tools ==
There are a number of [[Development/Tools|Development Tools]] that are either required or helpful when building KDE Software. For these you will usually want to use the stable packages provided by your distribution.

You may want to use a graphical IDE for your development work:
* [http://www.kdevelop.org/ KDevelop 4]
* [[Development/Tools/Eclipse|Eclipse]]
* [[/Using_an_IDE_with_KDE4|Using an IDE with KDE4]]

== Contributing To KDE ==
Once you have a copy of KDE built you can then start contributing back to KDE. The pages below will help you find out how you can help make KDE even better.

[[Image:Action_tool.svg|right|32px]]
* [[Contribute|Contribute]]
* [[Contribute/Send_Patches|Send Patches]]
* [[Contribute/Bugsquad|Bugsquad]]

[[Category:Build_KDE]]

Getting Started

2011-06-04T09:26:30Z

Odysseus: /* Introduction */

{{warning|These pages are currently being completely re-written to reflect the new KDE infrastructure and may not be in a consistent state. Information and commands on some page may no longer be valid and should be used with care.}}

{{Template:I18n/Language Navigation Bar|Getting_Started}}

== Introduction ==
There are many different ways to become involved in the KDE Community, ranging all the way from a simply using our software through to being a core platform developer.

You can find more general information on getting involved in KDE at the following links:
* [http://kde.org/community/getinvolved/ Getting Involved in KDE]
* [[Contribute|Contribute to KDE]]

This section of KDE TechBase is designed to help get you started in participating in the technical side of the KDE community. It will explain to you how KDE Software is structured and built, and how you can participate by building KDE for yourself.

{{note|'''Quickstart:''' If you're impatient to get started without understanding what you are doing then we recommend you use one of the available [[/Build#Scripted_Builds|Build Scripts]].}}

== Using KDE Software ==
If you just want to use stable KDE software for your everyday computing needs, then you do not need to build KDE Software for yourself. You should instead use the software installer provided by your Linux distribution to install KDE package.

The best place to learn how to do this is through your distributions normal support channels, although you may find some useful information on the following pages:
* [http://www.kde.org/download/distributions.php Distributions shipping KDE]
* [[/Build/Distributions|Install KDE Software on Linux and BSD Distributions]]
* [[Projects/KDE_on_Windows/Installation|Install KDE Software on Windows]]
* Mac OS X does not currently have an installer available for KDE Software, but you can simplify building it by using [http://mac.kde.org/?id=build MacPorts or Fink]

== Getting Help ==
If you are looking for help in using the KDE Workspace or KDE Applications then please visit the [http://userbase.kde.org/ KDE UserBase].

If you have any questions or problems with building or developing KDE Software please feel free to [[Development/Getting_Help|ask for help]]. However, be patient while waiting for a response, and try to work through the problem yourself, we aren't going to do it ''all'' for you. Working your way through and understanding why something doesn't work is a good way to learn how to do things the right way.

== Building and Running KDE Software From Source ==

There are several possible ways to build and install KDE software and the method you choose depends on what you want to do with the software. In particular if you are only wanting to build and develop a single application you may not need to build the entire KDE Development Platform to do so. You can read more about this on the [[Getting_Started/Build/Methods|Build Methods page]].

The following sections explain the steps you need to understand and give the instructions you need to follow to successfully build KDE Software from source:

* [[/Sources|How the KDE Source Code is structured]]
* [[/Build|How to Build and Install the software]]
* [[/Run|How to Run the software]]

== Development Model ==
TODO: General introduction to the dev model, release cycles, etc.

* [[Schedules/Release_Schedules_Guide|The KDE Release Schedule]]
* [[Development/Software_Engineering_Framework|The KDE Software Engineering Framwork]]
* [[Policies|KDE Development Policies and Procedures to follow]]
* [[Policies/Application_Lifecycle|The development lifecycle for a new application]]

== Development Tools ==
There are a number of [[Development/Tools|Development Tools]] that are either required or helpful when building KDE Software. For these you will usually want to use the stable packages provided by your distribution.

You may want to use a graphical IDE for your development work:
* [http://www.kdevelop.org/ KDevelop 4]
* [[Development/Tools/Eclipse|Eclipse]]
* [[/Using_an_IDE_with_KDE4|Using an IDE with KDE4]]

== Contributing To KDE ==
Once you have a copy of KDE built you can then start contributing back to KDE. The pages below will help you find out how you can help make KDE even better.

[[Image:Action_tool.svg|right|32px]]
* [[Contribute|Contribute]]
* [[Contribute/Send_Patches|Send Patches]]
* [[Contribute/Bugsquad|Bugsquad]]

[[Category:Build_KDE]]

Getting Started/Build/Methods

2011-06-04T09:10:14Z

Odysseus: /* Deciding How To Build KDE Software */

{{warning|These pages are currently being completely re-written to reflect the new KDE infrastructure and may not be in a consistent state. Information and commands on some page may no longer be valid and should be used with care.}}

{{Template:I18n/Language Navigation Bar|Getting Started/Build/Methods}}

== Deciding How To Build KDE Software ==

There are several possible ways to build and install KDE software and the method you choose depends on what you want to do with the software once it is built.

You may want to:
* Develop a standalone application using the KDE Development Platform
* Develop one of the KDE Applications
* Develop the KDE Workspace or the KDE Platform
* Test the latest KDE Software or an earlier stable version

In particular, for application development you may only need to use the KDE Development Platform stable packages from your distribution rather than building it all yourself.

The tables below provide some guidance in making this decision.

TODO: Complete these options.

<table border="1" width="100%" cellpadding="5">
<tr>
<td width="75%">'''Usage'''</td>
<td width="25%">'''Method'''</td>
</tr>
<tr>
<td width="75%">Developing an application outside of the KDE development infrastructure using the stable KDE Development Platform.</td>
<td width="25%" style="background: #FFEFD3">'''Packaged Stable Release'''</td>
</tr>
<tr>
<td width="75%" rowspan=2>Developing an application outside of the KDE development infrastructure using features from the unstable KDE Development Platform.</td>
<td width="25%" style="background: #FFFEE4">'''Snapshot Build'''</td>
</tr>
<tr>
<td width="25%" style="background: #9FD6D2">'''Unstable Source Build'''</td>
</tr>
<tr>
<td width="75%">Developing an application in the KDE SC using the stable KDE Development Platform.</td>
<td width="25%" style="background: #D0ECEA">'''Stable Source Build'''</td>
</tr>
<tr>
<td width="75%">Developing an application in the KDE SC using features in the unstable KDE Development Platform.</td>
<td width="25%" style="background: #9FD6D2">'''Unstable Source Build'''</td>
</tr>
<tr>
<td width="75%">Developing the unstable KDE Development Platform.</td>
<td width="25%" style="background: #9FD6D2">'''Unstable Source Build'''</td>
</tr>
</table>

<table border="1" width="100%" cellpadding="5">
<tr>
<td width="25%">'''Method'''</td>
<td width="75%">'''Description'''</td>
</tr>
<tr>
<td width="25%" style="background: #FFEFD3">'''Stable Release Packages'''</td>
<td width="75%">Install a stable release of the KDE Development Platform from packages using your distributions standard software installer.</td>
</tr>
<tr>
<td width="25%" style="background: #FFEFD3">'''Unstable Packages'''</td>
<td width="75%">Install an unstable version of the KDE Development Platform using your distributions standard software installer. Some distributions provide unstable packages for Nightly Snapshots, Weekly Snapshots, or unstable development releases.</td>
</tr>
<tr>
<td width="25%" style="background: #FFFEE4">'''Snapshot Build'''</td>
<td width="75%">Build a snapshot of the source code as at a given time or release from a tarball download. These may be stable or unstable releases or nightly snapshots</td>
</tr>
<tr>
<td width="25%" style="background: #D0ECEA">'''Stable Source Build'''</td>
<td width="75%">Build a version of the source code for an official release directly from the source repository.</td>
</tr>
<tr>
<td width="25%" style="background: #9FD6D2">'''Unstable Source Build'''</td>
<td width="75%">Build the current unstable development code directly from the source repository.</td>
</tr>
</table>

[[Category:Build KDE]]

Getting Started

2011-06-04T09:05:54Z

Odysseus: /* Building and Running KDE Software From Source */

{{warning|These pages are currently being completely re-written to reflect the new KDE infrastructure and may not be in a consistent state. Information and commands on some page may no longer be valid and should be used with care.}}

{{Template:I18n/Language Navigation Bar|Getting_Started}}

== Introduction ==
There are many different ways to become involved in the KDE Community, ranging all the way from a simply using our software through to being a core platform developer.

You can find more general information on getting involved in KDE at the following links:
* [http://kde.org/community/getinvolved/ Getting Involved in KDE]
* [[Contribute|Contribute to KDE]]

This section of KDE TechBase is designed to help get you started in participating in the technical side of the KDE community. It will explain to you how KDE Software is structured and built, and how you can participate by building KDE for yourself.

{{note|'''Quickstart:''' If you're impatient to get started without understanding the background then we recommend you use one of the available [[/Build#Scripted_Builds|Build Scripts]].}}

== Using KDE Software ==
If you just want to use stable KDE software for your everyday computing needs, then you do not need to build KDE Software for yourself. You should instead use the software installer provided by your Linux distribution to install KDE package.

The best place to learn how to do this is through your distributions normal support channels, although you may find some useful information on the following pages:
* [http://www.kde.org/download/distributions.php Distributions shipping KDE]
* [[/Build/Distributions|Install KDE Software on Linux and BSD Distributions]]
* [[Projects/KDE_on_Windows/Installation|Install KDE Software on Windows]]
* Mac OS X does not currently have an installer available for KDE Software, but you can simplify building it by using [http://mac.kde.org/?id=build MacPorts or Fink]

== Getting Help ==
If you are looking for help in using the KDE Workspace or KDE Applications then please visit the [http://userbase.kde.org/ KDE UserBase].

If you have any questions or problems with building or developing KDE Software please feel free to [[Development/Getting_Help|ask for help]]. However, be patient while waiting for a response, and try to work through the problem yourself, we aren't going to do it ''all'' for you. Working your way through and understanding why something doesn't work is a good way to learn how to do things the right way.

== Building and Running KDE Software From Source ==

There are several possible ways to build and install KDE software and the method you choose depends on what you want to do with the software. In particular if you are only wanting to build and develop a single application you may not need to build the entire KDE Development Platform to do so. You can read more about this on the [[Getting_Started/Build/Methods|Build Methods page]].

The following sections explain the steps you need to understand and give the instructions you need to follow to successfully build KDE Software from source:

* [[/Sources|How the KDE Source Code is structured]]
* [[/Build|How to Build and Install the software]]
* [[/Run|How to Run the software]]

== Development Model ==
TODO: General introduction to the dev model, release cycles, etc.

* [[Schedules/Release_Schedules_Guide|The KDE Release Schedule]]
* [[Development/Software_Engineering_Framework|The KDE Software Engineering Framwork]]
* [[Policies|KDE Development Policies and Procedures to follow]]
* [[Policies/Application_Lifecycle|The development lifecycle for a new application]]

== Development Tools ==
There are a number of [[Development/Tools|Development Tools]] that are either required or helpful when building KDE Software. For these you will usually want to use the stable packages provided by your distribution.

You may want to use a graphical IDE for your development work:
* [http://www.kdevelop.org/ KDevelop 4]
* [[Development/Tools/Eclipse|Eclipse]]
* [[/Using_an_IDE_with_KDE4|Using an IDE with KDE4]]

== Contributing To KDE ==
Once you have a copy of KDE built you can then start contributing back to KDE. The pages below will help you find out how you can help make KDE even better.

[[Image:Action_tool.svg|right|32px]]
* [[Contribute|Contribute]]
* [[Contribute/Send_Patches|Send Patches]]
* [[Contribute/Bugsquad|Bugsquad]]

[[Category:Build_KDE]]

Getting Started

2011-06-04T09:04:50Z

Odysseus: /* Building and Running KDE Software From Source */

{{warning|These pages are currently being completely re-written to reflect the new KDE infrastructure and may not be in a consistent state. Information and commands on some page may no longer be valid and should be used with care.}}

{{Template:I18n/Language Navigation Bar|Getting_Started}}

== Introduction ==
There are many different ways to become involved in the KDE Community, ranging all the way from a simply using our software through to being a core platform developer.

You can find more general information on getting involved in KDE at the following links:
* [http://kde.org/community/getinvolved/ Getting Involved in KDE]
* [[Contribute|Contribute to KDE]]

This section of KDE TechBase is designed to help get you started in participating in the technical side of the KDE community. It will explain to you how KDE Software is structured and built, and how you can participate by building KDE for yourself.

{{note|'''Quickstart:''' If you're impatient to get started without understanding the background then we recommend you use one of the available [[/Build#Scripted_Builds|Build Scripts]].}}

== Using KDE Software ==
If you just want to use stable KDE software for your everyday computing needs, then you do not need to build KDE Software for yourself. You should instead use the software installer provided by your Linux distribution to install KDE package.

The best place to learn how to do this is through your distributions normal support channels, although you may find some useful information on the following pages:
* [http://www.kde.org/download/distributions.php Distributions shipping KDE]
* [[/Build/Distributions|Install KDE Software on Linux and BSD Distributions]]
* [[Projects/KDE_on_Windows/Installation|Install KDE Software on Windows]]
* Mac OS X does not currently have an installer available for KDE Software, but you can simplify building it by using [http://mac.kde.org/?id=build MacPorts or Fink]

== Getting Help ==
If you are looking for help in using the KDE Workspace or KDE Applications then please visit the [http://userbase.kde.org/ KDE UserBase].

If you have any questions or problems with building or developing KDE Software please feel free to [[Development/Getting_Help|ask for help]]. However, be patient while waiting for a response, and try to work through the problem yourself, we aren't going to do it ''all'' for you. Working your way through and understanding why something doesn't work is a good way to learn how to do things the right way.

== Building and Running KDE Software From Source ==

There are several possible ways to build and install KDE software and the method you choose depends on what you want to do with the software. In particular if you are only wanting to build and develop a single application you may not need to build the entire KDE Development Platform to do so. You can read more about this on the [[Getting_Started/Build/Methods|Build Methods page]].

The following sections explain the steps you need to understand and give the instructions you need to follow to successfully build KDE Software from source:

* [[/Sources|Obtain the Source Code for the software]]
* [[/Build|Build and Install the software]]
* [[/Run|Run the software]]

== Development Model ==
TODO: General introduction to the dev model, release cycles, etc.

* [[Schedules/Release_Schedules_Guide|The KDE Release Schedule]]
* [[Development/Software_Engineering_Framework|The KDE Software Engineering Framwork]]
* [[Policies|KDE Development Policies and Procedures to follow]]
* [[Policies/Application_Lifecycle|The development lifecycle for a new application]]

== Development Tools ==
There are a number of [[Development/Tools|Development Tools]] that are either required or helpful when building KDE Software. For these you will usually want to use the stable packages provided by your distribution.

You may want to use a graphical IDE for your development work:
* [http://www.kdevelop.org/ KDevelop 4]
* [[Development/Tools/Eclipse|Eclipse]]
* [[/Using_an_IDE_with_KDE4|Using an IDE with KDE4]]

== Contributing To KDE ==
Once you have a copy of KDE built you can then start contributing back to KDE. The pages below will help you find out how you can help make KDE even better.

[[Image:Action_tool.svg|right|32px]]
* [[Contribute|Contribute]]
* [[Contribute/Send_Patches|Send Patches]]
* [[Contribute/Bugsquad|Bugsquad]]

[[Category:Build_KDE]]

Getting Started/Build

2011-06-04T08:58:22Z

Odysseus: /* Build and Install */

{{warning|These pages are currently being completely re-written to reflect the new KDE infrastructure and may not be in a consistent state. Information and commands on some page may no longer be valid and should be used with care.}}

{{Template:I18n/Language Navigation Bar|Getting Started/Build}}

== Introduction ==

This page provides an overview of the KDE build process. Once you complete the steps described here you will have a complete KDE development system customized to your needs.

== Build Steps ==

This section will briefly explain the concepts and steps involved in building software so you are not being asked to blindly follow some recipes you do not understand.

It is assumed you are at least familiar with the basics of using the command line.

Once you have read the summary you can see a [[/Example|worked example here]].

=== Source ===

The ''Source'' step is obtaining a local copy of the source code that you want to build. For a detailed explanation of where to obtain the source code and how KDE stores and organizes our source code please read the [[Getting_Started/Sources|KDE Sources section]].

The two main options here are to either download a snapshot tarball of the code, or to directly access the source code repository. For developing on the unstable branch of the KDE SC it is recommended you directly access the required repositories.

=== Configure ===

The ''Configure'' step is setting up how the source code is to be built and installed.

=== Build ===

The ''Build'' step is compiling the source code and linking it to other libraries to create the new executables and libraries.

=== Install ===

The ''Install'' step is copy the new executables and libraries somewhere that they can be found and run from.

=== Update ===

The ''Update'' step is updating an existing build to use the latest version of the source code and then re-building and re-installing it.

== Scripted Builds ==

The easiest way to build the KDE SC from scratch is to use one of the build scripts that are available. This approach is highly recommended for those new to building KDE SC as it takes care of the Source, Configure, Build, Install and Update steps for you. The builds remain compatible with the manual methods of building KDE SC so you can change later if you want.

* The [[/kdesrc-build|kdesrc-bld]] script by Michael Pyne
* The [http://michael-jansen.biz/build-tool build-tool] script by Michael Jansen

== Platform Specific Information ==

The build process described in these pages is kept as simple and generic as possible, but it is generally assumed you are building KDE4 on Linux. Extra information about building KDE Software on specific distributions or platforms, or under certain conditions can be found at the following links:

* [[/Distributions|Linux, BSD and other *nix based distributions]]
* [[/Windows|Microsoft Windows]]
* [[/Mac_OS_X|Apple Mac OS X]]
* [[/KDE4/on_virtual_machines|On a Virtual Machine]].
* [[/Historic|Building historic versions of KDE Software (KDE3 and KDE2)]]

== Stable versus Unstable ==

A stable build is a released and supported version of KDE Software, such as KDE SC 4.6. This software is guaranteed to remain unchanged other than bug-fixes. You will want a Stable build if you want to use the KDE Software for normal use or to develop bug fixes.

An unstable build is the latest development version of KDE Software and is not guaranteed to build or run properly at any given time. You will want an Unstable build if you want to develop new features for KDE Software.

In Git, the Unstable branch is called Master while in Subversion it is called Trunk.

== Build and Install ==

You need to complete each of the following steps to build and/or install a working KDE development system. Manually building KDE Software requires that you first set up the build environment and install the required development tools and libraries.

* Choose the appropriate [[/Methods|Build Method]] for your requirements
* Set up your [[/Environment|Build Environment]]
* Choose the appropriate [[/Recipes|Build Recipes]] for your requirements and environment
* Install the [[/Requirements|Build Requirements]]
* Install or build [[/Qt|Qt]]
* Install or build [[/KDE_Support|KDE Support]]
* Install or build [[/KDE_Development_Platform|KDE Development Platform]]
* Install or build [[/KDE_Workspace|KDE Workspace]]

These steps are yet to be completed:
* [[/KDE_Applications|Build KDE Applications]]

== Troubleshooting The Build ==

Compile and Linking errors are frequent sources of discouragement. Make careful note of the first occurrence of an error in your build process. It could be as simple as a bad environment variable, an unexpected version of a library or missing prerequisite. Please read the instructions carefully.

Please review your logs and do searches for fixes. If you cannot find a solution, try the [[/Troubleshooting|Troubleshooting]] page. If you still cannot resolve the problem then please [[Development/Getting_Help|ask for help]] on IRC or a Mailing List.

[[Category:Build KDE]]

Getting Started

2011-06-04T08:55:43Z

Odysseus: /* Building and Running KDE Software From Source */

{{warning|These pages are currently being completely re-written to reflect the new KDE infrastructure and may not be in a consistent state. Information and commands on some page may no longer be valid and should be used with care.}}

{{Template:I18n/Language Navigation Bar|Getting_Started}}

== Introduction ==
There are many different ways to become involved in the KDE Community, ranging all the way from a simply using our software through to being a core platform developer.

You can find more general information on getting involved in KDE at the following links:
* [http://kde.org/community/getinvolved/ Getting Involved in KDE]
* [[Contribute|Contribute to KDE]]

This section of KDE TechBase is designed to help get you started in participating in the technical side of the KDE community. It will explain to you how KDE Software is structured and built, and how you can participate by building KDE for yourself.

{{note|'''Quickstart:''' If you're impatient to get started without understanding the background then we recommend you use one of the available [[/Build#Scripted_Builds|Build Scripts]].}}

== Using KDE Software ==
If you just want to use stable KDE software for your everyday computing needs, then you do not need to build KDE Software for yourself. You should instead use the software installer provided by your Linux distribution to install KDE package.

The best place to learn how to do this is through your distributions normal support channels, although you may find some useful information on the following pages:
* [http://www.kde.org/download/distributions.php Distributions shipping KDE]
* [[/Build/Distributions|Install KDE Software on Linux and BSD Distributions]]
* [[Projects/KDE_on_Windows/Installation|Install KDE Software on Windows]]
* Mac OS X does not currently have an installer available for KDE Software, but you can simplify building it by using [http://mac.kde.org/?id=build MacPorts or Fink]

== Getting Help ==
If you are looking for help in using the KDE Workspace or KDE Applications then please visit the [http://userbase.kde.org/ KDE UserBase].

If you have any questions or problems with building or developing KDE Software please feel free to [[Development/Getting_Help|ask for help]]. However, be patient while waiting for a response, and try to work through the problem yourself, we aren't going to do it ''all'' for you. Working your way through and understanding why something doesn't work is a good way to learn how to do things the right way.

== Building and Running KDE Software From Source ==

There are several possible ways to build and install KDE software and the method you choose depends on what you want to do with the software once it is built. In particular if you are only wanting to build and develop a single application you may not need to build the entire KDE Development Platform to do so. You can read more about this on the [[Getting_Started/Build/Methods|Build Methods page]].

The following sections explain the steps you need to understand and give the instructions you need to follow to successfully build KDE Software from source:

* [[/Sources|Obtain the Source Code for the software]]
* [[/Build|Build and Install the software]]
* [[/Run|Run the software]]

== Development Model ==
TODO: General introduction to the dev model, release cycles, etc.

* [[Schedules/Release_Schedules_Guide|The KDE Release Schedule]]
* [[Development/Software_Engineering_Framework|The KDE Software Engineering Framwork]]
* [[Policies|KDE Development Policies and Procedures to follow]]
* [[Policies/Application_Lifecycle|The development lifecycle for a new application]]

== Development Tools ==
There are a number of [[Development/Tools|Development Tools]] that are either required or helpful when building KDE Software. For these you will usually want to use the stable packages provided by your distribution.

You may want to use a graphical IDE for your development work:
* [http://www.kdevelop.org/ KDevelop 4]
* [[Development/Tools/Eclipse|Eclipse]]
* [[/Using_an_IDE_with_KDE4|Using an IDE with KDE4]]

== Contributing To KDE ==
Once you have a copy of KDE built you can then start contributing back to KDE. The pages below will help you find out how you can help make KDE even better.

[[Image:Action_tool.svg|right|32px]]
* [[Contribute|Contribute]]
* [[Contribute/Send_Patches|Send Patches]]
* [[Contribute/Bugsquad|Bugsquad]]

[[Category:Build_KDE]]

Contribute

2011-05-30T14:16:18Z

Odysseus: /* Reporting Bugs */

{{Template:I18n/Language Navigation Bar|Contribute}}
This page intends to give an overview of the different aspects of KDE development in particular for programming related issues. '''The KDE project welcomes anyone willing to help'''.

{{note|There are a lot of ways to get involved in KDE development, which can be summed up in several categories:
:''Documentation, Translation, Development, Usability, Accessibility, Artwork, Promotion
'''Not a coder? See KDE's pages on [http://kde.org/community/getinvolved/ how to get involved] to see other ways you can help. Also see: [[Contribute/Bugsquad|Bugsquad]]!'''
}}

== News and Mail Sources ==
The general direction of the KDE project is determined by those who do the work - there is no single high level plan for what KDE will look like in the future.

If you want to find out what is currently happening, then there are a number of sources you might like to consider:
; [http://www.kde.org/mailinglists/ Mailing Lists]
: Probably the best way to find out what's going on in KDE development. Archives are available [http://lists.kde.org here]

; [http://commitfilter.kde.org/ CommitFilter]
: Receive notification of commits to the KDE source code repositories in areas that interest you.

; [http://commit-digest.org/ KDE Commit-Digest]
: Weekly summary of commits to projects in the KDE source code repositories.

; [http://dot.kde.org/ The Dot]
: The KDE news site.

== Reporting Bugs ==

The easiest way to contribute to KDE is to [http://userbase.kde.org/Asking_Questions#Reporting_KDE_Bugs report any bugs] you find in KDE using the [https://bugs.kde.org/ KDE Bug Tracking System] (also known as Bugzilla).

If the application you are using crashes then the Dr Konqi utility will appear and guide you through the process of reporting the crash. Learn more by reading [[Development/Tutorials/Debugging/How_to_create_useful_crash_reports|how to create useful crash reports]].

== Getting Started with Coding ==
Getting started at coding for KDE is a matter of finding something to fix, and fixing it. You may want to consult the module overview to help find what you are looking for; once you have fixed something, you will want to send in a patch. If you do that a few times, you may want to apply for an SVN account so you can fix things directly.
* [[Contribute/List of KDE Modules|Module overview]]
* [[Contribute/Send Patches|Sending patches]]
* [[Contribute/Get a SVN Account|Applying for a KDE SVN Account]]
* [[Contribute/First Steps with your KDE SVN Account|First steps with your new SVN account]]

=== C++ ===
KDE is mostly written in C++. If you are not familiar with C++, you should do at least some work on it. There are a number of good books on C++ - an excellent source is [http://mindview.net/Books/TICPP/ThinkingInCPP2e.html Bruce Eckel's "Thinking in C++"], which is available both as a free download and as a printed document. It isn't essential to understand everything before you start in KDE, but you do need to understand basic syntax and operations.

=== Qt ===
To become proficient with KDE coding, you should understand the Qt toolkit. If you are not familiar with Qt, you should work through the tutorials included with [http://doc.qt.nokia.com/latest Qt Reference Documentation].

If you need a gentler introduction to Qt, or would just like an alternative view, then you may wish to look at the [http://qt4.digitalfanatics.org/tiqt/ The Independent Qt Tutorial] (Currently offline due to book contract).

If you prefer to learn Qt by reading a traditional book, take a look at the [http://qt.nokia.com/developer/books/ Books about Qt page]. More suggestions on becoming familiar with Qt4 are available [http://doc.qt.nokia.com/latest/how-to-learn-qt.html How to Learn Qt page].

=== KDE ===
A range of information on KDE techniques is available in the [[Development/Tutorials|tutorial section]]. Note that some of these tutorials still target KDE3, though they should be at least partly applicable.

You will also find useful information on KDE coding in the [[Development/FAQs|FAQs]] section. This information may also be somewhat dated for KDE4, however much of it is broadly applicable, even outside KDE.

You can also read [[Development/Further Information#Books|KDE coding books]].

Last, but by no means least, KDE comes with extensive class (Application Programmer Interface) documentation. This is available in the
[[Development/Tutorials/API Documentation|KDE API Reference Manuals]] section, which also contains a number of useful links on how to write or update the class documentation. You can also generate these on your own machine, or refer to a more up-to-date online version at [http://api.kde.org/ API Reference].

A more detailed description of the steps above is available in our [http://quality.kde.org/develop/howto/howtohack.php Programming Guide].

== Getting Involved in Bug Hunting and Application Quality ==

There is a large number of applications within KDE, and not all of them have a maintainer dedicated to managing bugs and generally helping out with all the issues associated with turning some working code into a polished application.

If you are interested in helping out with KDE, but don't know where to start, becoming a member of the KDE Quality Team might appeal to you - see the [http://quality.kde.org Quality Team website] for more information. Note that you do not need any programming skills to become involved. In particular developers regularly publish so-called [http://community.kde.org/KDE/Junior_Jobs Junior Jobs] to encourage new contributions.

Of course, you can become involved in bug hunting without being part of the KDE Quality Team - just create yourself an account on the KDE [http://bugs.kde.org bug tracking system], and start searching / sorting through the bugs. Again, you don't have to have programming skills - it helps the programmers enormously just to have a procedure that allows a bug to be consistently reproduced.

The [[Contribute/Bugsquad|Bugsquad]] tries to keep track of bugs in KDE software and make sure that valid bugs are noticed by developers. You do not need any programming knowledge to be in the Bugsquad; in fact it is a great way to return something to the KDE community if you cannot program.

==Getting Answers to Your Questions==
If your question concerns KDE development, your options are pretty much the same general user ones, with some modifications:
::* '''Read the Developer FAQ'''. Many common developer questions have been answered in the [[Development/FAQs|KDE Developer FAQ]]
::* '''Search/browse KDE websites'''. A lot of questions can also be answered from the KDE websites, and the documentation included on it. You can search all the KDE websites on the homepage. In addition, you can browse the [http://techbase.kde.org KDE TechBase website]. And if possible, help edit it for clarity, and use the talk page if something is unclear.
::* '''Search mailing lists'''. A lot of questions have already been answered on the KDE mailing lists, particular the lists kde-devel, kde2-porting, kde-core-devel, kde-games-devel, kfm-devel and koffice-devel. You can search these lists either at [http://lists.kde.org/ lists.kde.org]. You should always search for your answer before asking questions on the mailing lists. When you ask a question on a mailing list you are emailing thousands of people -- please do this only if the answer is not available through a simple search.
::* '''Search engines'''. Do not forget about your favorite search engine. One of the best search engines is Google. With Google you can also [http://groups.google.com/ search] the great bulk of Usenet news sites, which is also particularly helpful, especially for general programming and gcc-related questions.
::* '''Read the source code'''. http://websvn.kde.org and https://projects.kde.org/ are available to help browse code. Read some commit logs and diffs for the code you might want to work with, It adds perspective.
::* '''Ask on KDE mailing lists'''. If you still do not have an answer, try asking your question on one of the KDE mailing lists listed above.
::::* For questions relating to core development or third-party KDE development, unless you are particularly interested in [http://konqueror.kde.org/ Konqueror], [http://www.koffice.org/ KOffice], games or Java development, your main choice is [mailto:kde-devel@kde.org kde-devel] [mailto:kde-devel-request@kde.org?subject=subscribe (subscribe)].
::::* For questions relating to Konqueror development, your main choice is [mailto:kfm-devel@kde.org kfm-devel] [mailto:kfm-devel@kde.org?subject=subscribe (subscribe)]
::::* For questions relating to KOffice development, your main choice is [mailto:koffice-devel@kde.org koffice-devel] [mailto:koffice-devel-request@kde.org?subject=subscribe (subscribe)]
::::* For questions relating to games development, your main choice is [mailto:kde-games-devel@kde.org kde-games-devel] [mailto:kde-games-devel-request@kde.org?subject=subscribe (subscribe)]
::::* For questions relating to [http://qt.nokia.com/ Qt development], please use the fine [http://lists.trolltech.com/qt-interest/ Qt mailing list].
A full list of KDE mailing lists is available [http://www.kde.org/mailinglists/ here] and [http://mail.kde.org/mailman/listinfo here].

Contribute

2011-05-30T14:09:23Z

Odysseus: /* News and Mail Sources */

{{Template:I18n/Language Navigation Bar|Contribute}}
This page intends to give an overview of the different aspects of KDE development in particular for programming related issues. '''The KDE project welcomes anyone willing to help'''.

{{note|There are a lot of ways to get involved in KDE development, which can be summed up in several categories:
:''Documentation, Translation, Development, Usability, Accessibility, Artwork, Promotion
'''Not a coder? See KDE's pages on [http://kde.org/community/getinvolved/ how to get involved] to see other ways you can help. Also see: [[Contribute/Bugsquad|Bugsquad]]!'''
}}

== News and Mail Sources ==
The general direction of the KDE project is determined by those who do the work - there is no single high level plan for what KDE will look like in the future.

If you want to find out what is currently happening, then there are a number of sources you might like to consider:
; [http://www.kde.org/mailinglists/ Mailing Lists]
: Probably the best way to find out what's going on in KDE development. Archives are available [http://lists.kde.org here]

; [http://commitfilter.kde.org/ CommitFilter]
: Receive notification of commits to the KDE source code repositories in areas that interest you.

; [http://commit-digest.org/ KDE Commit-Digest]
: Weekly summary of commits to projects in the KDE source code repositories.

; [http://dot.kde.org/ The Dot]
: The KDE news site.

== Reporting Bugs ==

The easiest way to contribute to KDE is to report any bugs you find in KDE using the [https://bugs.kde.org/ KDE Bug Tracking System] (also known as Bugzilla).

If the application you are using crashes then the Dr Konqi utility will appear and guide you through the process of reporting the crash. Learn more by reading [[Development/Tutorials/Debugging/How_to_create_useful_crash_reports|how to create useful crash reports]].

== Getting Started with Coding ==
Getting started at coding for KDE is a matter of finding something to fix, and fixing it. You may want to consult the module overview to help find what you are looking for; once you have fixed something, you will want to send in a patch. If you do that a few times, you may want to apply for an SVN account so you can fix things directly.
* [[Contribute/List of KDE Modules|Module overview]]
* [[Contribute/Send Patches|Sending patches]]
* [[Contribute/Get a SVN Account|Applying for a KDE SVN Account]]
* [[Contribute/First Steps with your KDE SVN Account|First steps with your new SVN account]]

=== C++ ===
KDE is mostly written in C++. If you are not familiar with C++, you should do at least some work on it. There are a number of good books on C++ - an excellent source is [http://mindview.net/Books/TICPP/ThinkingInCPP2e.html Bruce Eckel's "Thinking in C++"], which is available both as a free download and as a printed document. It isn't essential to understand everything before you start in KDE, but you do need to understand basic syntax and operations.

=== Qt ===
To become proficient with KDE coding, you should understand the Qt toolkit. If you are not familiar with Qt, you should work through the tutorials included with [http://doc.qt.nokia.com/latest Qt Reference Documentation].

If you need a gentler introduction to Qt, or would just like an alternative view, then you may wish to look at the [http://qt4.digitalfanatics.org/tiqt/ The Independent Qt Tutorial] (Currently offline due to book contract).

If you prefer to learn Qt by reading a traditional book, take a look at the [http://qt.nokia.com/developer/books/ Books about Qt page]. More suggestions on becoming familiar with Qt4 are available [http://doc.qt.nokia.com/latest/how-to-learn-qt.html How to Learn Qt page].

=== KDE ===
A range of information on KDE techniques is available in the [[Development/Tutorials|tutorial section]]. Note that some of these tutorials still target KDE3, though they should be at least partly applicable.

You will also find useful information on KDE coding in the [[Development/FAQs|FAQs]] section. This information may also be somewhat dated for KDE4, however much of it is broadly applicable, even outside KDE.

You can also read [[Development/Further Information#Books|KDE coding books]].

Last, but by no means least, KDE comes with extensive class (Application Programmer Interface) documentation. This is available in the
[[Development/Tutorials/API Documentation|KDE API Reference Manuals]] section, which also contains a number of useful links on how to write or update the class documentation. You can also generate these on your own machine, or refer to a more up-to-date online version at [http://api.kde.org/ API Reference].

A more detailed description of the steps above is available in our [http://quality.kde.org/develop/howto/howtohack.php Programming Guide].

== Getting Involved in Bug Hunting and Application Quality ==

There is a large number of applications within KDE, and not all of them have a maintainer dedicated to managing bugs and generally helping out with all the issues associated with turning some working code into a polished application.

If you are interested in helping out with KDE, but don't know where to start, becoming a member of the KDE Quality Team might appeal to you - see the [http://quality.kde.org Quality Team website] for more information. Note that you do not need any programming skills to become involved. In particular developers regularly publish so-called [http://community.kde.org/KDE/Junior_Jobs Junior Jobs] to encourage new contributions.

Of course, you can become involved in bug hunting without being part of the KDE Quality Team - just create yourself an account on the KDE [http://bugs.kde.org bug tracking system], and start searching / sorting through the bugs. Again, you don't have to have programming skills - it helps the programmers enormously just to have a procedure that allows a bug to be consistently reproduced.

The [[Contribute/Bugsquad|Bugsquad]] tries to keep track of bugs in KDE software and make sure that valid bugs are noticed by developers. You do not need any programming knowledge to be in the Bugsquad; in fact it is a great way to return something to the KDE community if you cannot program.

==Getting Answers to Your Questions==
If your question concerns KDE development, your options are pretty much the same general user ones, with some modifications:
::* '''Read the Developer FAQ'''. Many common developer questions have been answered in the [[Development/FAQs|KDE Developer FAQ]]
::* '''Search/browse KDE websites'''. A lot of questions can also be answered from the KDE websites, and the documentation included on it. You can search all the KDE websites on the homepage. In addition, you can browse the [http://techbase.kde.org KDE TechBase website]. And if possible, help edit it for clarity, and use the talk page if something is unclear.
::* '''Search mailing lists'''. A lot of questions have already been answered on the KDE mailing lists, particular the lists kde-devel, kde2-porting, kde-core-devel, kde-games-devel, kfm-devel and koffice-devel. You can search these lists either at [http://lists.kde.org/ lists.kde.org]. You should always search for your answer before asking questions on the mailing lists. When you ask a question on a mailing list you are emailing thousands of people -- please do this only if the answer is not available through a simple search.
::* '''Search engines'''. Do not forget about your favorite search engine. One of the best search engines is Google. With Google you can also [http://groups.google.com/ search] the great bulk of Usenet news sites, which is also particularly helpful, especially for general programming and gcc-related questions.
::* '''Read the source code'''. http://websvn.kde.org and https://projects.kde.org/ are available to help browse code. Read some commit logs and diffs for the code you might want to work with, It adds perspective.
::* '''Ask on KDE mailing lists'''. If you still do not have an answer, try asking your question on one of the KDE mailing lists listed above.
::::* For questions relating to core development or third-party KDE development, unless you are particularly interested in [http://konqueror.kde.org/ Konqueror], [http://www.koffice.org/ KOffice], games or Java development, your main choice is [mailto:kde-devel@kde.org kde-devel] [mailto:kde-devel-request@kde.org?subject=subscribe (subscribe)].
::::* For questions relating to Konqueror development, your main choice is [mailto:kfm-devel@kde.org kfm-devel] [mailto:kfm-devel@kde.org?subject=subscribe (subscribe)]
::::* For questions relating to KOffice development, your main choice is [mailto:koffice-devel@kde.org koffice-devel] [mailto:koffice-devel-request@kde.org?subject=subscribe (subscribe)]
::::* For questions relating to games development, your main choice is [mailto:kde-games-devel@kde.org kde-games-devel] [mailto:kde-games-devel-request@kde.org?subject=subscribe (subscribe)]
::::* For questions relating to [http://qt.nokia.com/ Qt development], please use the fine [http://lists.trolltech.com/qt-interest/ Qt mailing list].
A full list of KDE mailing lists is available [http://www.kde.org/mailinglists/ here] and [http://mail.kde.org/mailman/listinfo here].

Development/Tutorials/Printing Print Dialog

2011-05-27T12:39:02Z

Odysseus: Created page with '== The mission == To display the Print Dialog and print a document. KDE uses the Qt Printing infrastructure, but adds extra standard features to the Print Dialog, as well as al...'

== The mission ==

To display the Print Dialog and print a document.

KDE uses the Qt Printing infrastructure, but adds extra standard features to the Print Dialog, as well as allowing applications to add their own extensions.

== The code ==

<code cppqt n>
#include <QtGui/QPainter>
#include <QtGui/QPrinter>

#include <KdePrintDialog>
#include <KPrintPreview>

#include <KApplication>
#include <KAboutData>
#include <KCmdLineArgs>

/*
This prints Hello World on your printer
*/

int main(int argc, char *argv[])
{
KAboutData aboutData( "test", "test", "1.0", "test",
KAboutData::License_GPL, "(c) 2006" );
KCmdLineArgs::init( argc, argv, &aboutData );
KApplication app;

KAction* m_printPreview = KStandardAction::printPreview(app, SLOT(slotFilePrintPreview()), actionCollection());

KHelloWorldPrintDialogWidget optionsWidget;

QPrinter printer;
printer.setFullPage(true);
QPrintDialog *printDialog = KdePrint::createPrintDialog(&printer, QList<QWidget*>() << &yourOptionsWidget, this);
printDialog.setWindowTitle(i18n("Print Hello World"));
if (printDialog.exec()) {
QPainter painter;
painter.begin(&printer);
painter.drawText(100,100,"Hello World");
if (optionsWidget.printMoreText()) {
}
painter.end();
// this makes the print job start
}
}

class KHelloWorldPrintDialogWidget : public QWidget
{
bool printMoreText();
void setPrintMoreText(bool state);

setWindowTitle(i18n("Your Options Tab Title"));
}

void KHelloWorld::slotFilePrintPreview() {
QPrinter printer;
KPrintPreview printPreview(&printer);
yourPrintDrawingRoutine(printer); // draws to the QPrinter
printPreview.exec();
}
</code>

== How to compile ==

=== CMakeLists.txt ===

<code>
find_package(KDE4 REQUIRED)
include_directories( ${KDE4_INCLUDES} )
kde4_add_executable(printhelloworld printtest.cpp)
target_link_libraries(printhelloworld ${${KDE4_KDECORE_LIBS} ${KDE4_KUTILS_LIBS} ${QT_QTGUI_LIBRARY})
</code>

=== Make and Run ===

Then do:
cmake .
make
./printhelloworld

[[Category:KDE4]]
[[Category:C++]]

Development/Tutorials

2011-05-27T12:13:02Z

Odysseus: /* Printing */

{{Template:I18n/Language Navigation Bar|Development/Tutorials}}

Tutorials are the fastest way of finding out what KDE will do for you, and how to do it. Here is a list of currently available tutorials '''for KDE4'''. Material for KDE3 and KDE2 is available on the bottom of this page.

== Introduction To KDE 4 Programming ==
Are you interested in writing applications with KDE 4? This tutorial series is aimed at those completely new to KDE programming.
;[[Development/Tutorials/First program|Hello World]]
:''A preliminary introduction to the very basics of KDE4 programming''

;[[Development/Tutorials/Using KXmlGuiWindow|Creating the Main Window]]
:''This tutorial shows you the magic of an application's most important thing: The main window.''

;[[Development/Tutorials/Using KActions|Using KActions]]
:''How to add actions to the menus and toolbars.''

;[[Development/Tutorials/Saving and loading|Saving and Loading]]
:''Introduces the KIO library while adding loading and saving support to our application.''

;[[Development/Tutorials/KCmdLineArgs|Command line arguments]]
:''Adds the ability to specify which file to open from the command line to our text editor.''

== Basics ==
;[[Development/Tutorials/KDE4 Porting Guide|Porting Your Application]]
:''Help Porting Applications from Qt3/KDE3 to Qt4/KDE4''

;[[Development/Tutorials/CMake|Introduction to CMake]]
:''How to use the CMake build system used by KDE4.''

;[[Development/Tutorials/Common Programming Mistakes|Common Programming Mistakes]]
:''Various common mistakes made while developing Qt and KDE applications and how to avoid them.''

;[[Development/Tutorials/Debugging Linker Errors|Debugging Linker Errors]]
:'How to understand and debug errors from the linker, at compile time.''

;[[Development/Tutorials/Using Qt Designer|Using Qt Designer to build user interfaces]]
:''How to create UI files with designer, and how to integrate them into a KDE program.''

;[[Development/Tutorials/Using Qt Creator|Using Qt Creator to develop your KDE program]]
:''How to integrate Qt Creator use into KDE development.''

;[[Development/Tutorials/Creating Libraries|Creating Libraries to share code]]
:''How to add the library to the buildsystem and how to prepare the source code.''

;[[Development/Tutorials/Session_Management|Session Management]]
:''Make your application aware of X sessions''

== Testing And Debugging ==

;[[Development/Tutorials/Debugging|Debugging your application]]
:''Tips, tools and techniques to apply when debugging your KDE application''

;[[Development/Tutorials/Unittests|Writing Unittests for Qt4 and KDE4 with QTestLib]] ([http://developer.kde.org/documentation/tutorials/writingunittests/writingunittests.html Original link])
:''Tutorial by [mailto:bradh@frogmouth.net Brad Hards] that describes how to write unit tests using the QTestLib framework. It is presented as an example based tutorial, and is still under development.''

;[[Development/Tutorials/Code_Checking|Semi-automatic ways to detect code errors]]
:''Techniques you can use to detect errors in KDE code''

== Managing Configuration Data With KConfig ==
;[[Development/Tutorials/KConfig|Introduction To KConfig]]
:''An overview of the KConfig classes and how to use them in your application code''

;[[Development/Tutorials/Using KConfig XT|Using KConfig XT]]
:''Tutorial on how to efficiently use the KConfig XT framework.''

;[[Development/Tutorials/Updating KConfig Files|Updating KConfig Files]]
:''Tutorial on how to write an update script to keep changes in your application's config file format in sync with the user's already existing config file''

== Services: Applications and Plugins ==
;[[Development/Tutorials/Services/Introduction|Introduction to the Services Framework]]
:''An overview of the services framework in KDE and what it provides the application developer. Covers the system configuration cache (SyCoCa), the source data files and what the indexed information can be used for.''

;[[Development/Tutorials/Services/Traders|Finding Services Using Trader Queries]]
:''How to find services, such as plugins or mimetypes, that are indexed in the SyCoCa using Trader Query Syntax''

;[[Development/Tutorials/Services/Plugins|Creating and Loading Plugins Using KService]]
:''Learn how to define custom plugin types, find installed plugins (including 3rd party plugins) and load them in an easy and portable fashion using KService.''

== Localization ==
See also [[Localization|Localization portal]].

;[[Development/Tutorials/Localization/Unicode|Introduction To Unicode]]
:''An introduction to what Unicode is as well as how to handle Unicode data in KDE applications.''

; [[Development/Tutorials/Localization/i18n|Writing Applications With Localization In Mind]]
:''This tutorial covers what localization is, why it's important and how to ensure your application is ready to be localized. A must read for all application developers.''

; [[Development/Tutorials/Localization/i18n Mistakes|Avoiding Common Localization Pitfalls]]
:''There are several common mistakes that prevent applications from being properly localized. Find out what they are and how to easily avoid them in this tutorial.''

; [[Development/Tutorials/Localization/Building KDE's l10n Module|Building KDE's Localization Module]]
:''Building and installing language support from KDE's localization (l10n) module is a good idea for those working on applications in the main KDE repository. Doing so will allow you to test your application in another language and spot problem areas. Learn how to do just that in this tutorial.''

; [[Development/Tutorials/Localization/i18n Build Systems|Incorporating i18n Into the Build System]]
:''Once your application is ready to be localized, the next step is to ensure that translation files are built automatically and kept up to date. This tutorial covers the necessary CMakeFiles.txt additions as well the process of distributing the resulting message catalogs with your application.''

; [[Development/Tutorials/Localization/i18n Challenges|Common i18n Challenges and Solutions]]
:''This tutorial covers challenges that you may eventually run into such as translating handbooks and other data that exists outside of the source code, merging and handling obsolete .po files, dealing with freezes, coding in languages other than English and creating independent releases of or moving applications between KDE modules.''

; [[Development/Tutorials/Localization/i18n_Semantics|Semantic Markup of Messages]]
:''To ensure consistent presentation and more meaningful representations of messages in applications, semantic markup can be applied to messages marked for translation using the KUIT system. This tutorial describes how this system works.''

; [[Development/Tutorials/Localization/i18n Krazy|Automated i18n Code Checking]]
:''The Krazy code checker scans KDE's code and reports common i18n mistakes.''

== Documentation ==

;[[Development/Tutorials/API_Documentation|API Documentation]]
:''This tutorial explains how to document your APIs properly.''

;[[Development/Tutorials/Man_Pages|Man Pages]]
:''Writing and Generating Reference Manual Pages.''

;Source Code
: http://websvn.kde.org

== Accessibility ==

;[[Development/Tutorials/Accessibility|Accessibility]]
:''This tutorial will explain how to make your application accessible.''

;[[Development/Tutorials/Text-To-Speech|Text-To-Speech]]
:''How to utilize Jovie text-to-speech service in your application.''

== Application Automation and Scripting ==

=== D-Bus ===
; [[Development/Tutorials/D-Bus/Introduction|Introduction to D-Bus]]
:''A straight-forward introduction to the core concepts in D-Bus from an application developer's perspective, this tutorial covers what D-Bus is and how it can be used by applications.''
; [[Development/Tutorials/D-Bus/Accessing Interfaces|Accessing D-Bus Interfaces]]
:''A step-by-step guide to calling D-Bus methods and connecting to D-Bus signals using QtDBus.''
; [[Development/Tutorials/D-Bus/Intermediate_D-Bus|Intermediate D-Bus]]
:''Tips to make use of QtDBus when faced with problematic real-world interfaces.''
; [[Development/Tutorials/D-Bus/Creating Interfaces|Creating D-Bus Interfaces]]
:''Learn how to expose functionality in your application by creating and using custom D-Bus interfaces. Covers generating the XML descriptions, instantiating interfaces at run time and setting up the build system with CMake.''
; [[Development/Tutorials/D-Bus/CustomTypes|Using Custom Types with D-Bus]]: ''Learn how to use your own types in classes exported on D-Bus. Covers marhaling and unmarshaling of objects, the integration of custom types into XML descriptions and registering the custom types with the Qt Meta Object system.''
; [[Development/Tutorials/D-Bus/Autostart Services|D-Bus Autostart Services]]
:''Turn your application into a D-Bus autostart service with this tutorial. This D-Bus feature, also known as "D-Bus service activation", will ensure that even when your application isn't running that D-Bus calls made to it will work by relying on the D-Bus daemon itself to start your app if and when needed.''
; [[Development/Tutorials/Porting_to_D-Bus|Porting from DCOP to D-Bus]]
: ''Port your applications from DCOP to D-Bus with this handy guide.''

=== Konqueror ===
; [[Development/Tutorials/Creating Konqueror Service Menus|Creating Konqueror Service Menus]]
:''This tutorial shows you how to create mimetype-specific actions in Konqueror's context menu (aka "servicemenus").''

=== Kross ===
; [[Development/Tutorials/Kross/Introduction|Introduction to Kross]]
:''An introduction to the Kross Scripting Framework.''

; [[Development/Tutorials/Kross/Hello_World|Hello World]]
:''A first application with working kross code.''

; [[Development/Tutorials/Kross/Call_Functions_in_Kross|Calling Functions in Kross]]
:''Simple demonstration of calling scripting functions''

; [[Development/Tutorials/Kross/Connecting_Signals_and_slots_in_Kross|Connecting Signals and Slots in Kross]]
:''Simple demonstration of connecting object signals with script slots''

; [[Development/Tutorials/Kross/Scripts-as-Plugins|Scripts as Plugins with Kross]]
:''This tutorial provides a step-by-step introduction how to integrate scripts as plugins into a KDE application.''

; [[Development/Tutorials/Kross/Script-Actions|Placing script actions in your application menus ]]
:''Simple demonstration on how to extend you application menus to execute script files.''

; [[Development/Tutorials/Kross/ActionCollections|How to use an ActionCollection ]]
:''A small Tutorial on How to use Kross::ActionCollections.''
{{:KOffice/Plugin Tutorials}}

=== SuperKaramba ===
; [[Development/Tutorials/SuperKaramba|SuperKaramba Tutorial]]
:''This tutorial provides an overview of SuperKaramba, theme files and scripting with Python, Ruby and JavaScript.''

=== System Activity ===

: [[Development/Tutorials/SystemActivity/Scripting|Writing script actions for the process's context menu]]
:''This tutorial shows how to add a context menu action to show custom information about a process.

== Plugins and KParts ==

; [[Development/Tutorials/Writing kontact plugins|Writing kontact plugins]]:''Kontact plugins are KParts. This tutorial describes how you can write one.''

; [[Development/Tutorials/Using KParts|Using KParts]]:''Learn how to load a KPart into an application window.''

; [[Development/Tutorials/Writing Qt Designer Plugins|Writing Qt Designer Plugins]]:''Add your widgets to Qt Designer and thus make them usable in UI files.''

== Search and Metadata ==

=== Strigi ===

; [[Development/Tutorials/Writing file analyzers|Writing file analyzers]]
:''File analyzers extract data from files to display in the file dialogs and file managers. The data gathered this way is also used to search for files. KDE4 allows the use of multiple analyzers per file type. This tutorial describes how you can write new analyzers.''

=== [http://nepomuk.kde.org Nepomuk] ===

See [[Development/Tutorials/Metadata/Nepomuk|Nepomuk tutorials]].

== Hardware Awareness (Solid) ==

;[[Development/Tutorials/Solid_Tutorials|Introduction to Solid]]
:''An introduction to using the Solid hardware discovery and interaction system in KDE applications.''

;[[Development/Tutorials/Solid_Network_Tutorial|Accessing Network Information]]
:''How to use the Solid system to get information about the network''

;[[Development/Tutorials/Solid_Device_Actions|Creating a Device Action]]
:''When your application is interested in registering actions with the system for removable hardware''

== Authorization and Privilege escalation (KAuth) ==
; [[Development/Tutorials/KAuth/KAuth_Basics|KAuth Basics]]
:''An overview of concepts and basic knowledge required to understand and use KAuth effectively''
; [[Development/Tutorials/KAuth/KAuth_Actions|Using KAuth actions in your application]]
:''How to execute KAuth actions in your application, and how to integrate them tightly into your UI''
; [[Development/Tutorials/KAuth/Helper_HowTo|Creating a KAuth helper to perform a privileged action]]
:''You will learn how to use KAuth's helpers and escalation facilities, and how to seamlessly make a privileged and non privileged portion of your application interact''
; [[Development/Tutorials/KAuth/KCM_HowTo|Creating a KCM requiring authorization upon saving]]
:''Learn how to use the high level KCModule API to create KCModules handling authorization, and its UI integration, on their own''

== Multimedia (Phonon) ==

;[[Development/Tutorials/Phonon/Introduction|Phonon]]
:''How to start with the multimedia API''

:''How to compile and use Phonon and its GStreamer backend on Linux using Qt 4.3.x''
::''This article gives you a quick brief of how you can use checkout, compile Phonon and its GStreamer backend on GNU/Linux with just Qt 4.3.x. Towards the end, the article also describes how a developer can make use of Phonon to create simple audio and video players. You can read the article [http://www.vcreatelogic.com/oss/docs/CompilingPhononOnLinux.pdf here]. You can download the editable OpenDocumentText file from [http://www.prashanthudupa.com/phonon/CompilingPhononOnLinux.odt here].''

;[[Development/Tutorials/Phonon/Backends|Writing Backends]]
:''How to start creating a new backend for the multimedia API''

;Resources
:''Please have a look at the [http://api.kde.org/kdesupport-api/kdesupport-apidocs/phonon-git/html/ online documentation] for information on the Phonon API. If you prefer using Qt Assistant or Qt Creator you can also use our [http://mts.ms/phonon-4.4.2.qch offline documentation].''

== Plasma ==

See [[Development/Tutorials/Plasma|Plasma tutorials]].

== Personal Information Management (Akonadi) ==

;[[Development/Tutorials/Akonadi/Application|Using Akonadi in Applications]]
:''Displaying and modifying data provided by Akonadi''

;[[Development/Tutorials/Akonadi/Resources|Developing Akonadi Resources]]
:''Akonadi Resources are agent programs which transport PIM data between Akonadi and a backend (files, servers, etc)''

;[[Development/Tutorials/Akonadi/SerializerPlugin|Using custom data types with Akonadi]]
:''Akonadi can handle arbitrary data as item payloads through the use of a plugin based serialization framework''

;[[Development/AkonadiPorting|Porting Applications which use KResource API]]
:''Applications using KDE's now deprecated KResource APIs, e.g. KABC or KCal, need to be ported to use their Akonadi equivalents''

== Kate / Kwrite ==

;[[Development/Tutorials/Kate/KTextEditor Plugins|Getting started with KTextEditor plugins]]
:''Creating your first KTextEditor plugin''

;[[Development/Tutorials/Kate/KTextEditor_Plugins_Advanced|Developing a plugin with configuration dialog]]
:''Adding a configuration dialog to the Time & Date example''

;[[Development/Tutorials/Kate/KTextEditor_Example|A small Editor]]
:''Create a small application using KTextEditor''

== KDevelop ==

;[[Development/KDevelop-PG-Qt_Introduction|KDevelop-PG-Qt Introduction]]
:''Information on the KDevelop parser generator, useful for language plugins.''

==Printing==

KDE mostly uses the [http://doc.qt.nokia.com/latest/printing.html Qt Printing infrastructure].

;[[Development/Tutorials/Printing Hello World|Hello World]]
:''Introduction to the KDE printing system''

;[[Development/Tutorials/Printing Print Dialog|Print Dialog]]
:''Using the KDE print dialog''

== kioslaves ==
* [[Development/Tutorials/KIO Slaves/Using KIO Slaves in your Program|Using kioslaves in your Program]]
* [[Development/Tutorials/KIO Slaves/Hello World|Creating a Hello-World kioslave]]

== Collaboration ==

=== Open Collaboration Services (libattica) ===

;[[Development/Tutorials/Collaboration/Attica/Introduction|Introduction to Attica]]
:''In this tutorial a simple widget showing information about a Person on the server is created.''

=== Get Hot New Stuff ===

;[[Development/Tutorials/Collaboration/HotNewStuff/Introduction|Get Hot New Stuff 3 - Download]]
:''How to use KHotNewStuff3 in your application.''<br>

;[[Development/Tutorials/Collaboration/HotNewStuff/Updates|Get Hot New Stuff 3 - Checking for Updates]]
:''How to check if updates for installed stuff are available without showing the dialog/widget.''<br>

;[[Development/Tutorials/Collaboration/HotNewStuff/Upload|Get Hot New Stuff 3 - Upload]]
:''How to add an upload dialog to your application.''<br>

Old links for KNS2 and KNS1 content:<br>

;[[Development/Tutorials/K Hot New Stuff2|Introduction to Get Hot New Stuff 2]]
:''A short tutorial about how to use KHotNewStuff2 in your application. Deprecated, use version 3''
;[[Development/Tutorials/Introduction to Get Hot New Stuff|Introduction to Get Hot New Stuff]]
:''An introduction to the developer-friendly network update system that allows KDE applications to fetch new application data at runtime in a user friendly manner.''

;[[Development/Tutorials/KNewStuffSecure|KNewStuff Secure]] ([http://developer.kde.org/documentation/tutorials/knewstuffsecure/index.html Original Link])
:''Tutorial showing how to share resources in a secured way (KDE 3.4 and later).'' By András Mantia <amantia@kde.org>.

== Goya ==
; [[Development/Tutorials/Introduction to Goya usage|Introduction to Goya usage]]
:''An introduction for the Goya subsystem usage, which allows you to easily add widgets to your itemviews and connect their signals to your code, as they were real widgets.''

; [[Development/Tutorials/Introduction to Goya usage 2|Introduction to Goya usage (part 2)]]
:''The second part of the tutorial, with a slightly more complex example than the first part.''

== Other programming languages ==

=== Python ===

;[http://www.learningpython.com/2008/09/20/an-introduction-to-pyqt/ An Introduction to PyQt]
:''Starting off''

;[http://lateral.netmanagers.com.ar/stories/BBS47.html PyQt by Example]
:''Another introduction to PyQt''

;[[Development/Languages/Python/PyKDE_WebKit_Tutorial|PyKDE WebKit Tutorial]]
:''A simple web browser application in PyKDE''

;[[Development/Tutorials/Python introduction to signals and slots|101 Introduction to signals and slots]]
:''A simple introduction to Qt's signal and slot architecture.''

;[[Development/Languages/Python/PyKDE_DBus_Tutorial|PyKDE DBus Tutorial]]
:''An introduction to DBus communication using PyKDE''

;[[Development/Languages/Python/PyKDE_Knotify_Tutorial|PyKDE KNotify Tutorial]]
:''An introduction to Knotify (Notifications and KJobs) using PyKDE''

=== Ruby ===

;[http://developer.kde.org/language-bindings/ruby/kde3tutorial/index.html KDE Ruby Korundum tutorial]
:''A ruby version of Antonio Larrosa Jiménez's KDE tutorial by Richard Dale. See the [[Development/Languages/Ruby|Ruby Developers Corner]] for Qt tutorials and other info.''

;[[Development/Tutorials/Qt4_Ruby_Tutorial|Qt4 Ruby Tutorial]]
:''Nokia's fabulous introductory tutorial to Qt, translated to Ruby.''

;[[Development/Tutorials/Plasma/RubyApplet|Creating a Plasma Widget in Ruby]]
:''Tutorial that shows how to create your first Plasma Applet using the Ruby language.''

;[[Development/Tutorials/Developing_Qt4_Applications_using_Qt_Designer_and_Ruby_on_Kubuntu|Developing Qt4 Applications using Qt Designer and Ruby on Kubuntu]]
:''Tutorial that shows how to design a simple User Interface in Qt Designer and then use the resulting widget in a Qt Ruby application we build from scratch.''

;[[Development/Languages/Ruby/Ruby-Qt/KDE_Book|Ruby-Qt/KDE Book]]
:''There is also an approach to create an Ruby-Qt/KDE Book under a free license. The content will be created in this wiki.''

=== Shell ===

;[[Development/Tutorials/Shell_Scripting_with_KDE_Dialogs|Shell Scripting with KDE dialogs]] ([http://developer.kde.org/documentation/tutorials/kdialog/t1.html Original Link])
:''Tutorial by [mailto:bradh@frogmouth.net Brad Hards] that describes how to use KDE dialogs in shell scripts with kdialog. It is presented as an example based tutorial.''

== Graphics Programming ==

;[[Development/Tutorials/Graphics/Performance|QPainter Perfomance]]
:''Hints on avoiding common mistakes leading to poor performance when using QPainter''

== Using the KDE Games Libraries ==
;[[Development/Tutorials/Games/KStandardGameAction| KStandardGameAction]]
:''Using libkdegames to make your game fit the kdegames standard''
;[[Development/Tutorials/Games/Highscores| Highscores]]
:''Implementing a simple highscore table into your game''
;[[Development/Tutorials/Games/Theme Selector| Theme Selector]]
:''Using the libkdegames theme selection dialog''
;[[Development/Tutorials/Games/Palapeli Patterns| Palapeli Slicers]]
:''Creating a slicer plugin for Palapeli''

=== KGLEngine ===
;[[Development/Tutorials/Games/kglengine/kglengine-simpleBox| installation and your first KGLItem]]
:''start your first kglengine application''
;[[Development/Tutorials/Games/KGLEngine2d| kglpong]]
:''Now use our knowledge to make a pong''

=== KALEngine ===
;[[Development/Tutorials/Games/KALEngine| Play hello word sound]]
:''Using KALEngine for games sound development using openAL''
;[[Development/Tutorials/Games/KALEngine-music| Play music]]
:''Using KALEngine to play music in a stream''

== Using the KDE PIM Libraries ==
;[[Development/Tutorials/PIM/ical| iCalendar functionality]]
:''Using kcal to manage iCalendar files''

== Other tutorials ==

=== 2D Plotting (KPlotWidget) ===
;[[Development/Tutorials/KPlotWidget|Using the KDE data-plotting widget]]
:''This tutorial introduces KPlotWidget, which is used for 2-D data plotting. It includes information on simple usage of the widget (including adding and modifying data sets, and customizing the plot axes and labels), and advanced customization (including extending the widget through sub-classing).''

=== Spelling and Grammar Checking (Sonnet) ===
;[[Development/Tutorials/Sonnet/SonnetTutorial|Adding spell-checking or grammar-checking to KDE applications]]
:''This tutorial introduces Sonnet and how one may use it to add language correction to your KDE application. Sonnet's auxiliary features shall be described in a separate tutorial.''

=== Pixmap cache (KPixmapCache) ===
;[[Development/Tutorials/KPixmapCache|Using the KDE pixmap cache]]
:''This tutorial shows how to use KPixmapCache to cache e.g. pixmaps generated from SVGs or some data.''

=== Using MarbleWidget (Marble) ===
;[[Development/Tutorials/MarbleWidget|Using MarbleWidget]]
:''This short tutorial describes how to use the MarbleWidget in your project''

=== Using local SCM for KDE development ===
;[[Development/Git|Using Git to develop for KDE]]
:''Here you find how to use Git to develop for KDE''

=== Kwin effect tutorial (blog) ===
;[http://blog.martin-graesslin.com/blog/?p=258 blog by Martin Graesslin]
:''This tutorial guides you through the development of a simple KWin effect''

=== Implementing KSysGuard sensors and adding them ===
;[[Development/Tutorials/Sensors]]
:''This tutorial shows how to write and KSysGuard sensor and connect it to the systray.''
Runners

=== Porting an application from KSystemTrayIcon to KStatusNotifierItem ===
;[[Development/Tutorials/PortToKStatusNotifierItem]]
:''This tutorials shows how to port an application using KSystemTrayIcon to KStatusNotifierItem''

=== Using the KDE Wallet API for safe storage ===
;[[Development/Tutorials/KWallet]]
:"Brief introduction to the KWallet API which can be used for storing all kinds of sensitive information."

== KDE2 and KDE3 Materials ==

;[[Development/Tutorials/KDE3|KDE3 Tutorials]]
:''These tutorials cover topics related to KDE3.''

;[[Development/Tutorials/KDE2|KDE2 Tutorials]]
:''These tutorials cover topics related to KDE2.''

[[Category:KDE4]]