290 lines
9.9 KiB
Text
290 lines
9.9 KiB
Text
Contributing to Lumiera
|
|
=======================
|
|
:Author: Benny <Benny.Lyons@gmx.net>
|
|
:Date: Oct 2013
|
|
|
|
|
|
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
|
|
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
|
|
mailing list.
|
|
|
|
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_.
|
|
|
|
One very useful place to begin with using Git is the following:
|
|
link:http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html[basic Git tutorial at Kernel.org].
|
|
For more specific questions, you might consulte a link:http://gitref.org/[Git reference]
|
|
|
|
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.
|
|
|
|
|
|
Letting People Know Who You Are
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
------------------------------------------------------------
|
|
$ git config --global user.name "Your Name Comes Here"
|
|
$ git config --global user.email you@yourdomain.example.com
|
|
------------------------------------------------------------
|
|
|
|
Obtaining Lumiera Code
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
------------------------------------------------------------
|
|
$ git clone git://git.lumiera.org/LUMIERA
|
|
------------------------------------------------------------
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
|
|
Building Lumiera
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
------------------------------------------------------------
|
|
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`.
|
|
|
|
|
|
Once you've saved this file, you'll want to record your modifications to you
|
|
local Git repository:
|
|
|
|
------------------------------------------------------------
|
|
$ cd .../doc/users/tutorials
|
|
$ 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
|
|
Git to use emacs:
|
|
|
|
------------------------------------------------------------
|
|
$ git config --global core.editor emacs
|
|
------------------------------------------------------------
|
|
|
|
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 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 on the 'mob'
|
|
repository:
|
|
|
|
------------------------------------------------------------
|
|
$ git push git://git.lumiera.org/lumiera/mob master:refs/heads/YOURNAME
|
|
------------------------------------------------------------
|
|
|
|
This creates a new branch +YOURNAME+ on the mob repository.
|
|
|
|
Check that indeed your changes are public by visiting
|
|
link:http://Lumiera.org/gitweb[the Git-Web]. The lumiera/mob
|
|
repository should indicate [green]#right now# as its ``Last Change'' entry.
|
|
|
|
Thereafter, notify the other developers on the mailing list and they may examine
|
|
your code into the main project line.
|
|
|
|
|
|
Lumiera Communication Channels
|
|
--------------------------------
|
|
|
|
|
|
Mailing List
|
|
~~~~~~~~~~~~
|
|
------------------------------------------------------------
|
|
lumiera@lists.lumiera.org
|
|
------------------------------------------------------------
|
|
|
|
|
|
IRC Meetings
|
|
~~~~~~~~~~~~
|
|
|
|
The Lumiera community generally meets on the second Thursday of each month at
|
|
20:00 UTC 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.
|
|
|