From bc185742aab41183bfdb4c06ffef05bed79ccafe Mon Sep 17 00:00:00 2001 From: Benny Date: Thu, 10 Oct 2013 23:22:21 +0200 Subject: [PATCH] DOC: rewrite and improve the 'contributing' tutorial; a Git 'mini HOWTO' --- doc/user/tutorials/contributing.txt | 241 +++++++++++++++++++++++----- 1 file changed, 199 insertions(+), 42 deletions(-) diff --git a/doc/user/tutorials/contributing.txt b/doc/user/tutorials/contributing.txt index aa73a496e..1f5771d7a 100644 --- a/doc/user/tutorials/contributing.txt +++ b/doc/user/tutorials/contributing.txt @@ -1,29 +1,53 @@ -Contributing to Lumiera -======================= +Contributing to +Lumiera+ +========================= -All files in the Lumiera project are managed by *Git*. Although *Git* was +Introduction +------------ + +This document is aimed at helping newcomers to contribute quickly to the +project. + +There are two major obstacles faced by people new to +Lumiera+: + + - _how_ can I contribute to +Lumiera+ + - _where_, i.e., in which areas of +Lumiera+, can I contribute + +Git plays a fundamental role in +Lumiera+. It features as one of the main +methods in making contributions to +Lumiera+. For this reason we provide a +short +Lumiera+ specific introduction on Git. This is less of a Git introduction, +and more of how-to-obtain +Lumiera+ code and publish your changes to the +Lumiera+ +community. While Git is not the only means of making your contributions +avialable to the project, it is the method of choice if you were to become more +involved in the project. Of course, cou may also post your work to the ++Lumiera+ mailing list, or simply ask one of the regular developers. + ++Lumiera+ is an ambituous project. While many areas of the project are involved and +require considerable experience, some sections require less experience whereas +certain aspects might be ideal to new programmers. Thus we attempt here to +describe a number of areas in the project to assist you in selecting an area in +which you might like to make a contribution. +Of course, you are more than welcome--and even encouraged--to select other areas +in +Lumiera+ toawards which you would like to contribute. + + +Git: Essentials for +Lumiera+ +----------------------------- +All files in the +Lumiera+ project are managed by *Git*. Although *Git* was primarily brought to life to manage source code, it plays a fundamental role in -the Lumiera project. It is central to communication and contribution in the -project. If you'd like to contribute to Lumiera, you will have to acquire some +the +Lumiera+ project. It is central to communication and contribution in the +project. If you'd like to contribute to +Lumiera+, you will have to acquire some understanding of *Git* at some stage or other. Please note, this is not the only -way to contribute to Lumiera, you can always send direct contributions to the +way to contribute to +Lumiera+, you can always send direct contributions to the mailing list. -The Lumiera project uses an infrastructure based on *Git*, the distibuted +The +Lumiera+ project uses an infrastructure based on *Git*, the distibuted sourcecode management software. This deliberately places the barrier for contributing very low: No formal ``commit permission'' is necessary; you can start right away and present your first results to the _mob repository_. - - -Git: Lumiera Essentials ------------------------ - One very useful place to begin with using Git is the following: http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html[basic -instructions]. In particular, the following parts: - -http://gitref.org/ +instructions]. In particular, the following parts: http://gitref.org/ In the following, we assume you have set up Git on your system. If you are experiencing problems with Git, just ask the Lumiera community. @@ -37,32 +61,102 @@ $ git config --global user.name "Your Name Comes Here" $ git config --global user.email you@yourdomain.example.com ------------------------------------------------------------ -Obtaining Lumiera Code -~~~~~~~~~~~~~~~~~~~~~~ +Obtaining +Lumiera+ Code +~~~~~~~~~~~~~~~~~~~~~~~~ ------------------------------------------------------------ $ git clone git://git.lumiera.org/LUMIERA ------------------------------------------------------------ -If everything goes ok, you should have the Lumiera source code. However, you do +If everything goes ok, you should have the +Lumiera+ source code. However, you do not have enough code to build as there are some external packages missing that -are required to build Lumiera. Please refer to the +are required to build +Lumiera+. + +Obtaining Packages Required by +Lumiera+ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Apart from the +Lumiera+ source code, you'll require additional packages to build ++Lumiera+. These additional packages are of two kinds: + + - Packages not normally part of your distribution + - Packages normally available with your distrubtion + +There are two packages most likely not available with your operating system +distribution, so you'll need to obtain the source code for these packages and +compile: +Nobug+ and +Gdl+. + + +Nobug +^^^^^ +------------------------------------------------------------ +git clone git://git.pipapo.org/nobug +cd nobug +autoreconf -i +mkdir build && cd build +../configure +make +sudo make install +------------------------------------------------------------ + +Gdl +^^^ +------------------------------------------------------------ +git clone git://git.lumiera.org/gdl-package +cd gdl-package +./configure +make +sudo make install +------------------------------------------------------------ + +Additional Packages +^^^^^^^^^^^^^^^^^^^ +We'll describe obtaining the following packages for Debian, for other Linux +distributions, please refer to our mailing list. + +------------------------------------------------------------ +sudo apt-get install build-essential autoconf scons valgrind libtool git-core \ +libboost-dev libboost-program-options-dev libboost-regex-dev libboost-filesystem-dev \ +libgavl-dev libgdl-1-dev libgtkmm-2.4-dev librsvg2-dev libxv-dev +------------------------------------------------------------ + + +Please refer to the link:building.html[building-lumiera tutorial] on how to obtain all packages to -build Lumiera. +build +Lumiera+. -Contributing -~~~~~~~~~~~~ +Building +Lumiera+ +~~~~~~~~~~~~~~~~~~ -So you are ready to go, you can edit and commit your changes to the -lumiera code locally in your cloned repository. Please commit frequently, do -small commits which fix or improve only one single thing and try to use -meaningful commit messages. +------------------------------------------------------------ +cd LUMIERA +scons +------------------------------------------------------------ + +If +Lumiera+ is built correctly on your system, you should be able to shoot up +the +Lumiera+ GUI. + +------------------------------------------------------------ +cd target +lumiera +------------------------------------------------------------ + +Congratulations! Now we can move on to making contributions. + +Contributing Your Efforts to the +Lumiera+ Community +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +So you are ready to go. + +Browse through the source files. For your first contributions, you might prefer +to modify an existing file. Do so, go ahead and edit a file. Once you are +finished, save your changes. Let's assume, as an example, you've made changes to this file: _.../doc/users/tutorials/contributing.txt_. -Here's how to add your changes to Git: +Once you've saved this file, you'll want to record your modifications to you +local Git repository: ------------------------------------------------------------ $ cd .../doc/users/tutorials @@ -70,28 +164,43 @@ $ git add contributing.txt $ git commit contributing.txt -m "Corrected a grammatical error in section Git" ------------------------------------------------------------ +You can repeat the process to add more modifications. Experience has shown the +frequent commits is the practice of choice for others to follow what you have +been doing. + + +So it is strongly advised to commit frequently, do small commits which fix or +improve only one single thing or topic, or many things connected to a single +topic, i.e., correct a consistent spelling mistake spread over many files, to a +and try to use meaningful commit messages. + You can, of course, add more detailed information to your commit message. To do -this, you'll have to set-up git to use your favourite editor. Here's how to get +this, you'll have to set-up Git to use your favourite editor. Here's how to get Git to use emacs: ------------------------------------------------------------ $ git config --global core.editor emacs ------------------------------------------------------------ -Then while commiting, do not use the _-m_ option. Your editor will appear -requiring you to enter your comments. Enter, as your first line, a one line -summary of less than 80 characters in length (some applications use this line -for various purposes and longer entries tend to cause difficulties). +Then while commiting, do not use the +-m+ option. Your editor will appear, +after you issue the +git commit+ command, and prompt you to enter your comments. +Enter, as your first line, a one line summary of less than 60 characters in +length (some applications use this line for various purposes and longer entries +tend to cause difficulties). The line following your one line summary should be blank. Then on the third -line, you can begin your exposition on your changes. +line, you can begin your exposition in as much detail as you like on your +changes. Publishing Your Contribution ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +So all changes made up to now have been local to your own working environment. +The next thing to do is to make your work available to the +Lumiera+ community. Check that you didn't break anything, by running the testsuite. -Finally you can push your changes to the lumiera server to the 'mob' repository: +Finally you can +push+ your changes to the +Lumiera+ server on the 'mob' +repository: ------------------------------------------------------------ $ git push git://git.lumiera.org/lumiera/mob master:refs/heads/YOURNAME @@ -103,26 +212,74 @@ Check that indeed your changes are public by visiting http://www.lumiera.org/gitweb [http://www.lumiera.org/gitweb]. The lumiera/mob repository should indicate 'right now' as its _Last Change_ entry. -Thereafter, notify the other developers on the mailinglist and they may merge +Thereafter, notify the other developers on the mailing list and they may examine your code into the main project line. -Lumiera Communication Channels ------------------------------- ++Lumiera+ Communication Channels +-------------------------------- -The Mailing List -~~~~~~~~~~~~~~~~ - +Mailing List +~~~~~~~~~~~~ +------------------------------------------------------------ lumiera@lists.lumiera.org +------------------------------------------------------------ IRC Meetings ~~~~~~~~~~~~ -The Lumiera community generally meets on the second Wednesday of each month at -20:00 uucp on: _freenode #Lumiera_. + +The +Lumiera+ community generally meets on the second Wednesday of each month at +20:00 uucp on: +------------------------------------------------------------ +freenode#Lumiera +------------------------------------------------------------ All are more than welcome to join and to contribute to the discussions there. ++Lumiera+: The Project +---------------------- + - GUI + - Proc Layer + - Backend + - Website and its associated paraphernalia + - Contents of the website + - Miscellaneous +GUI +--- +The Lumiera design does not restrict the application to having a single GUI, in +fact, many user interfaces should be possible. +The initial GUI on which considerable work has already been done has been +implemented using the GTK toolkit. However, considerable more work needs to be +done on this present GUI. + +One immediate task that needs attention is to port the current GUI from +GTK2 to GTK 3. + +Of course, you may prefer to start from scratch using a different toolkit, +i.e. Qt. Contributions are are also most welcome. + + +Proc Layer +---------- + + +Backend +------- + + +Website and its associated paraphernalia +---------------------------------------- + + +Contents of the website +----------------------- + + +Miscellaneous +------------- +Do you havve any ideas? Please speak up on the mailing list or on IRC. +Such are always welcome.