Projects/KDE on Windows/Development Workflow - Revision history

Tfry: /* Basics */

2013-02-13T17:13:31Z

‎Basics

Tfry: /* Review and Pushing */

2013-02-13T17:07:30Z

‎Review and Pushing

Tfry: /* Review and Pushing */

2013-02-13T17:05:09Z

‎Review and Pushing

Tfry at 16:16, 11 December 2012

2012-12-11T16:16:12Z

Tfry: svn sources from external repos are at download/svn-src. More markup.

2012-12-11T16:09:24Z

svn sources from external repos are at download/svn-src. More markup.

AnneW: added consistency markup

2012-12-11T10:17:53Z

added consistency markup

Tfry: Initial draft complete

2012-12-10T18:28:42Z

Initial draft complete

Tfry at 17:01, 10 December 2012

2012-12-10T17:01:15Z

Tfry: Start working on a workflow page for KDE on Windows. More to come.

2012-12-10T13:05:35Z

Start working on a workflow page for KDE on Windows. More to come.

New page

= Development Workflow for KDE on Windows =

= Under Contruction! =

== Basics ==

Before we start: This page will not tell you how to diagnose and address problems or shortcomings in source code and build files. We assume you know all that already, or are willing to read up on any missing bits, on your own (but for some hints on useful tools and techniques, be sure to visit [[Development/Tutorials/Debugging/Debugging on MS Windows]], and [[../Tools]]. The pupose of this page is to give you an outline of the specific steps needed for preparing, testing, and publishing patches in the KDE on Windows project.

== Use emerge ==

You are using [[Getting_Started/Build/Windows/emerge|emerge]] to build your KDE on Windows development environment, right? If not, start doing so now. It's mandatory. Some variables to check in your emerge setup:

* EMERGE_BUILDTYPE: You may want to set this to "Debug"
* EMERGE_LOG_DIR: Setting this is highly useful, so you can review (long) build logs.
* GIT_AUTHOR_*/GIT_COMMITTER_*: Useful if you want to be able to make commits directly from your source tree.
* Be sure you are on the branch you want to be on!

== Where are the emerge build files ==

== Where are the sources ==

* git / svn / others

== Debugging and testing ==

* build directory
* mingw32-make
* emerge -i
* emerge --update
* diffutils

== Creating patches ==

* emerge --createpatch
* Adding to build_xyz.py
* Renaming build_xyz.py?
* Don't forget to test from a clean workdir.

== Review and Pushing ==

* reviewboard, mailing list, IRC
* git commands (short)
* merging to / from master

@@ Line 89: / Line 89: @@
 git log && git status   # always review before pushing
 git push origin master}}
 === Backporting ===

@@ Line 61: / Line 61: @@
 git push}}
-TODO:
+=== Which branches should you push your fix to? ===
-* Where to do your changes (which branches)
-* Should you merge to / from master?
+More often than not, your fix is relevant to more than one branch of KDE. Typically you will do your work on the latest release branch (''kde-4.10'' at the time of this writing), and merge your changes into ''master'' (which will be the basis of future releases). There is no formal policy on which old branches (former release branches such as ''kde-4.7'') remain supported, however it does make sense to keep branches for at least some time, even after a new series of KDE has been created.

@@ Line 14: / Line 14: @@
 * Be sure you are on the branch you want to be on!
-== Where are the emerge build files ==
+== Where are the emerge build files? ==
 Often some builds will fail for trivial reasons, like a download failing because the file has moved. This type of error (but also missing or wrong configuration options, and many others) can be corrected in the emerge build files. These are in (subdirectories of) ''emerge/portage/''. Each package has its own subdirectory. In each subdirectory you will find at least one .py-file. I am not aware of any in-depth information on the semantics of these files, but most concepts should be fairly obvious, and if you are unsure, look at other build files for examples.
-== Where are the sources ==
+== Where are the sources? ==
 If the problem needs fixing somewhere inside the source tree, you may be wondering where to look for the sources.
@@ Line 35: / Line 35: @@
 == Creating patches ==
-When satisfied with your fix, create a patch with <code>emerge --createpatch packagename</code>. This will automatically diff your changes against an unmodified source tree, and create a suitable diff. It will be stored in ''%KDEROOT%''/build/''category''/''packagename''/.
+When satisfied with your fix, create a patch with <code>emerge --createpatch ''packagename''</code>. This will automatically diff your changes against an unmodified source tree, and create a suitable diff. It will be stored in ''%KDEROOT%''/build/''category''/''packagename''/.
 Next, you will copy this patch to the directory of the package's emerge build script. Add it to the build script using
-{{Input|1= self.patchToApply[ ' ''package_version'' ' ] = [(' ''patch_file_name.diff'' ', 1 ), ''optionally further patches'']}}
+{{Input|1= self.patchToApply[ '' 'package_version' '' ] = [('' 'patch_file_name.diff' '', 1 ), ''optionally further patches'']}}
 Don't forget to test your patch for a clean workdir:

@@ Line 23: / Line 23: @@
 * git-based sources are in subdirectories of ''%KDEROOT%''/git
-* svn-based sources are in subdirectories of ''%KDEROOT%''/svn
+* svn-based sources inside the KDE svn are in ''%KDEROOT%''/svn
 * archived sources are first downloaded to ''%KDEROOT%''/download. Then, the archives get unpacked to ''%KDEROOT%''/build/''category''/''packagename''/work/ .
 == Debugging and testing ==
-When developing a fix on the level of a package's source code, first locate the final source tree, as detailed above. You do your work directly in the source tree. For quick testing, you can cd to the build directory (''%KDEROOT%''/build/''category''/''packagename''/work/''compiler_buildtype-version''). Assuming configuration is already complete you can often build directly from there (for MinGW4 use ''mingw32-make'').
+When developing a fix on the level of a package's source code, first locate the final source tree, as detailed above. You do your work directly in the source tree. For quick testing, you can cd to the build directory (''%KDEROOT%''/build/''category''/''packagename''/work/''compiler_buildtype-version''). Assuming configuration is already complete you can often build directly from there (for MinGW4 use <code>mingw32-make</code>).
 You can also use <code>emerge --update</code> to run the build script, without discarding your changes (TODO: Does this apply to all packages, or only svn / git based ones?).
@@ Line 34: / Line 35: @@
 == Creating patches ==
-When satisfied with your fix, create a patch with ''emerge --createpatch packagename''. This will automatically diff your changes against an unmodified source tree, and create a suitable diff. It will be stored in ''%KDEROOT%''/build/''category''/''packagename''/.
+When satisfied with your fix, create a patch with <code>emerge --createpatch packagename</code>. This will automatically diff your changes against an unmodified source tree, and create a suitable diff. It will be stored in ''%KDEROOT%''/build/''category''/''packagename''/.
 Next, you will copy this patch to the directory of the package's emerge build script. Add it to the build script using

@@ Line 30: / Line 30: @@
 When developing a fix on the level of a package's source code, first locate the final source tree, as detailed above. You do your work directly in the source tree. For quick testing, you can cd to the build directory (''%KDEROOT%''/build/''category''/''packagename''/work/''compiler_buildtype-version''). Assuming configuration is already complete you can often build directly from there (for MinGW4 use ''mingw32-make'').
-You can also use ''emerge --update'' to run the build script, without discarding your changes (TODO: Does this apply to all packages, or only svn / git based ones?).
+You can also use <code>emerge --update</code> to run the build script, without discarding your changes (TODO: Does this apply to all packages, or only svn / git based ones?).
 == Creating patches ==
@@ Line 36: / Line 36: @@
 When satisfied with your fix, create a patch with ''emerge --createpatch packagename''. This will automatically diff your changes against an unmodified source tree, and create a suitable diff. It will be stored in ''%KDEROOT%''/build/''category''/''packagename''/.
 Next, you will copy this patch to the directory of the package's emerge build script. Add it to the build script using
+{{Input|1= self.patchToApply[ ' ''package_version'' ' ] = [(' ''patch_file_name.diff'' ', 1 ), ''optionally further patches'']}}
-  self.patchToApply[ ' ''package_version'' ' ] = [(' ''patch_file_name.diff'' ', 1 ), ''optionally further patches'']
 Don't forget to test your patch for a clean workdir:
+ {{Input|1= emerge --cleanbuild ''packagename''
-   emerge --cleanbuild ''packagename''
+emerge ''packagename''}}
-   emerge ''packagename''
 TODO: When should build scripts be renamed to reflect newer version? Ever?
@@ Line 54: / Line 52: @@
 If you are confident in your patch, here's an extremely reduced overview of the git commands involved in getting it included:
+{{Input|1=git add ''all files that you have touched''
-  git add ''all files that you have touched''
+git commit ''with a meaningful message, please''
-  git commit ''with a meaningful message, please''
+git log     # and
-  git log           # and
+git status  # to review your work. ''git status'' should typically say "1 commit ahead of origin".
-  git status     # to review your work. ''git status'' should typically say "1 commit ahead of origin".
+            # Important: If ''git status'' shows more than one commit, and you don't know why, ask for help!
-                         # Important: If ''git status'' shows more than one commit, and you don't know why, ask for help!
+git pull --rebase    # To synchronize with the central repository
-  git pull --rebase    # To synchronize with the central repository
+git push}}
-  git push
 TODO:
 * Where to do your changes (which branches)
 * Should you merge to / from master?

@@ Line 3: / Line 3: @@
 == Basics ==
-Before we start: This page will not tell you how to diagnose and address problems or shortcomings in source code and build files. We assume you know all that already, or are willing to read up on any missing bits, on your own (but for some hints on useful tools and techniques, be sure to visit [[Development/Tutorials/Debugging/Debugging on MS Windows]], and [[../Tools]]. The pupose of this page is to give you an outline of the specific steps needed for preparing, testing, and publishing patches in the KDE on Windows project.
+Before we start: This page will not tell you how to diagnose and address problems or shortcomings in source code and build files. We assume you know all that already, or are willing to read up on any missing bits, on your own (but for some hints on useful tools and techniques, be sure to visit [[Development/Tutorials/Debugging/Debugging on MS Windows]], and [[../Tools]]). The pupose of this page is to give you an outline of the specific steps needed for preparing, testing, and publishing patches in the KDE on Windows project.
 == Use emerge ==

@@ Line 1: / Line 1: @@
 = Development Workflow for KDE on Windows =
 == Basics ==
@@ Line 32: / Line 30: @@
 When developing a fix on the level of a package's source code, first locate the final source tree, as detailed above. You do your work directly in the source tree. For quick testing, you can cd to the build directory (''%KDEROOT%''/build/''category''/''packagename''/work/''compiler_buildtype-version''). Assuming configuration is already complete you can often build directly from there (for MinGW4 use ''mingw32-make'').
-* build directory
+You can also use ''emerge --update'' to run the build script, without discarding your changes (TODO: Does this apply to all packages, or only svn / git based ones?).
-* mingw32-make
-* emerge -i
-* emerge --update
-* diffutils
 == Creating patches ==
-* emerge --createpatch
+When satisfied with your fix, create a patch with ''emerge --createpatch packagename''. This will automatically diff your changes against an unmodified source tree, and create a suitable diff. It will be stored in ''%KDEROOT%''/build/''category''/''packagename''/.
-* Adding to build_xyz.py
-* Renaming build_xyz.py?
+Next, you will copy this patch to the directory of the package's emerge build script. Add it to the build script using
-* Don't forget to test from a clean workdir.
 == Review and Pushing ==
-* reviewboard, mailing list, IRC
+If unsure, ask on kde-window@kde.org, on IRC ([irc://irc.freenode.net/kde-windows]), or post your patches to reviewboard before committing.
-* git commands (short)
-* merging to / from master
+If you are confident in your patch, here's an extremely reduced overview of the git commands involved in getting it included: