Getting the source

Zoltan P edited this page Aug 18, 2013 · 3 revisions
Clone this wiki locally

Table of Contents

GIT on Github

The main source code repository is on Github, at the address:

 https://github.com/ktechlab/ktechlab

For cloning it, the following URL can be used

 git@github.com:ktechlab/ktechlab.git`

The master branch should be mostly stable. Feature branches are created for implementing new functionality of fixing bugs, and they are merged as they become ready for the general public.

GIT on sourceforge

Since we talked about switching source-code management to git for a long time, this section should clarify the benefits, we might get, when actually doing the switch. Since sourceforge.net now supports git repositories for hosted projects, one large argument against using git is no longer valid. You can find a short introduction on how to use the sourceforge.net git-service here.

Getting the source from code repositories

Currently there are four repositories in the project, their URLs are listed here:

Main ktechlab repository:

 git://ktechlab.git.sourceforge.net/gitroot/ktechlab/ktechlab

User repositories:

 git://ktechlab.git.sourceforge.net/gitroot/ktechlab/ktl-alonzotg
 git://ktechlab.git.sourceforge.net/gitroot/ktechlab/ktl-j_ohny_b
 git://ktechlab.git.sourceforge.net/gitroot/ktechlab/ktl-zoltan_p

Also in each repository, there are more branches. It's recommended to check this page to see what contains each repository. The status as of march 2010 is:

  • ktechlab repository: in sync with SVN, including branches
  • ktl-j_ohny_b repository:
    • master: the upcoming 0.4 version, for Qt4 and KDE4
    • routing: initial implementation of connector routing
  • ktl-zoltan_p repository:
    • master: same as ktl-j_ohny_b/master
    • simulationmanager: feature-branch to implement the simulation plugin
    • testing-1: initial implementation of math testing code
It's recommended to test master branch, as that is somewhat stable and it will be released when it's completed.

The following commands can be used to retrieve the code:

Note: the following expressions should be substituted with the appropriate values:

 <repository URL>
 <repository name>
 <branchname>

Clone a repository:

 git clone <repository URL>

This command should create a new directory, called as the repository.

Change to the newly created directory:

 cd <repository name>

Create a local branch:

 git branch --track <branchname> origin/<branchname>

Checkout the local branch:

 git checkout <branchname>

Now the code can be found in the current directory. Now you can start Compiling the source.

An example: routing from ktl-j_ohny_b

 git clone git://ktechlab.git.sourceforge.net/gitroot/ktechlab/ktl-j_ohny_b
 cd ktl-j_ohny_b/
 git checkout -b routing --track origin/kde4-port

Suggested organization

We have multiple repositories within the KTechLab project. There is one repository, upstream, which is used as the main repository. You will find the latest development code in here (known as the master-branch) as well as stable branches and release tags. Only a limited group of developers has write-access to the upstream repository. Development of new features will be done in separate repositories, one for each developer. These repositories regularly pull the latest code from upstream to be in sync. After a new feature is ready for testing, a merge request can be sent to ktechlab-devel. Other developers can then pull the feature from the developers repository and review and test the patches. If the patches are okay, they will be merged into upstream.

Developer repositories don't need to be hosted on sourceforge.net. If you like to use other hosting services like gitorious.org or github.com, feel free to do so.

Hints for git users

Git's commands are similar to those SVN uses. Sometimes their meaning is slightly different. For instance git commit won't submit any chances to the remote repository (remember, you have got a clone of that repository on your computer). Git ships with a very good documentation in form of man-pages. Use git help [command] to see a particular man-page. It's also recommended having a copy of one of the git-cheat-sheets around, if you are new to git. This can prevent you from a lot of trouble ;) Don't be afraid to destroy something, or do ugly things to the repository. As long, as you don't push your changes after an emergency, everything will be all right. Find me (johnyb or jables) in IRC (#ktechlab on freenode) or drop a mail to ktechlab-devel, if you have any questions/problems.

You should create a global .gitconfig file, if you have never used git. It stores information like your name and email and some configuration regarding git itself.

git config --global user.email "<your.email@server.tld>"
git config --global user.name "<your name>"
git config --global user.signingkey "<your pgp-keyid>"
You should set these options in any case. Your name and email are used with every commit you do and you should make sure this information is correct. A signingkey is needed to digitally sign so called tags. Tags can also be created without signing them, but it's less secure, because anybody could put your name and email into the config and tag things in your name. (Just write access to the repository will limit the number of persons, able to do this).
git config --global color.ui true
git config --global pager "less -FXRS"
This will add nice colours to git's output to improve readability. Change the pager variable to start less with "-FXRS" to improve readability in diff-output, too. Unlike SVN, git pipes every output through $PAGER, to improve access to large output.
git config --global alias.st status
git config --global alias.ci commit
git config --global alias.co checkout
git config --global alias.lg "log -p"
git config --global alias.br branch
If you are used to SVN command line, you might like these aliases.

Another thing I learned to appreciate is to use the zsh in combination with it's .zshrc from grml. (Look for the wget command on this page, to find the file.) This config-file works fine in non-debian distributions. It has nice auto-completion features for most SCMs and if it detects the current directory to be managed by an SCM, it will show you the branch or the revision (in case of SVN), directly in the prompt. This feature will prevent most cases of "committing to the wrong branch"-errors.

SVN - depreacted

Please note that SVN is deprecated. Active development is performed in Git. SVN is still accessible, but it won't receive updates. This section is kept for archival purposes.

These instructions are copied from Compiling the source#Development Versions. Note that the most of the development of 0.4 branch is done in the GIT repositories.

The development svn snapshot can be downloaded via

 svn co https://ktechlab.svn.sourceforge.net/svnroot/ktechlab/trunk ktechlab

To build the version from trunk, just check it out and run

 make -f Makefile.cvs

in the projects root directory. This will generate the configure script and after that you can do

 ./configure --prefix=$(kde-config --prefix)
 make
 su -c "make install" 

as usual.

For sourceforge's more general instructions, see the sourceforge.net help page.

Organisation

Main development takes place in a directory called trunk. In this directory a bleeding-edge version of KTechLab can be found. The rule for every bleeding-edge software applies here, too: "Beware of it, it might eat your kitten!". Anyway, you might find the latest code and new components in this part of our code, so if you are willing to test and don't mind some glitches (of course we try to keep trunk as stable as possible), we encourage you to do check it out.

Besides trunk there are 2 directories. branches is used to develop a version (or branch) of KTechLab, where a special feature is implemented or a stable version is maintained there with bug-fixes or translation updates. tags is used to keep snapshots of different states of the source-code tree like stable versions.