Development Workflow for KDE on Windows

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 Windows/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.

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.

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).

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?).

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/.

Next, you will copy this patch to the directory of the package's emerge build script. Add it to the build script using

self.patchToApply[  'package_version'  ] = [( 'patch_file_name.diff' , 1 ), optionally further patches]

Don't forget to test your patch for a clean workdir:

emerge --cleanbuild packagename
emerge packagename

TODO: When should build scripts be renamed to reflect newer version? Ever?

Of course in many cases your fix should really become part of the "upstream" package source code. In particular, when patching KDE, you will probably want to commit your fixes to the KDE git repository, directly, in additon (when building an already finalized release of KDE), or instead of creating an emerge patch.

Review and Pushing

If unsure, ask on [email protected], on IRC ([1]), or post your patches to reviewboard before committing.

If you are confident in your patch, here's an extremely reduced overview of the git commands involved in getting it included:

git add all files that you have touched
git commit with a meaningful message, please
git log     # and
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!
git pull --rebase    # To synchronize with the central repository
git push

Which branches should you push your fix to?

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.

Forward merging

In general you should first commit/push your fix to the oldest branch that it applies to. After that, merge it into the more recent branches, up to (and including) master. Branches before kde-4.10 were not git mergeable, so you would do cherry-picking like this:

git checkout kde-4.10 && git pull origin kde-4.10
git cherry-pick commit_on_previous_branch  # possibly more than one commit to cherry-pick
git log && git status   # always review before pushing
git push origin kde-4.10

Branches from kde-4.10 onwards are mergeable, so once your fix is in kde-4.10, you should use:

git checkout kde-4.11 && git pull origin kde-4.11
git merge origin kde-4.10
# resolve conflicts if needed
git log && git status   # always review before pushing
git push origin kde-4.11

Rinse and repeat for every existing release branch (let's say that's kde-4.15), then finally repeat once more for master:

git checkout master && git pull origin master
git merge origin kde-4.15
# resolve conflicts if needed
git log && git status   # always review before pushing
git push origin master

Resolving merge conflicts

If you need to resolve merge conflicts, simply edit the files are required, then git add these files as usual and git commit, then git push.

Backporting

In case a fix is already on a later branch, but needs to be applied to an earlier branch, use cherry-picking:

git checkout kde-4.7 && git pull origin kde-4.7
git cherry-pick commit_on_later_branch  # possibly more than one commit to cherry-pick
git log && git status   # always review before pushing
git push origin kde-4.7

TODO: Will it be possible to back-merge from 4.11 to 4.10?