308 lines
12 KiB
Text
308 lines
12 KiB
Text
Contributing to Lumiera
|
|
=======================
|
|
:Author: Benny <Benny.Lyons@gmx.net>
|
|
:Date: Oct 2013
|
|
:toc:
|
|
|
|
|
|
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_ can I contribute, i.e., in which areas of Lumiera.
|
|
|
|
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
|
|
available to the project, it is the method of choice if you were to become more
|
|
involved in the project. Of course, you may also post your work to the
|
|
Lumiera mailing list, or simply ask one of the regular developers.
|
|
|
|
Lumiera is an ambitious 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 towards which you would like to contribute.
|
|
|
|
|
|
How to contribute to Lumiera
|
|
----------------------------
|
|
|
|
Git: Essentials for Lumiera
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
All files in the Lumiera project are managed by *Git*, the distributed sourcecode
|
|
management software. 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. This deliberately
|
|
places the barrier for contributing very low: Everyone works on his own
|
|
repository, no formal ``commit permission'' is necessary; you can start
|
|
right away and present your first results to the _mob repository_.
|
|
|
|
First steps with Git
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
One very useful place to begin with learning Git is the
|
|
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. So the next step
|
|
will be to learn how to build Lumiera from source code. Please refer to the
|
|
link:building.html[building-Lumiera tutorial] for a more in-depth description
|
|
of the necessary steps. The next section gives a brief summary of this process.
|
|
|
|
|
|
Build Lumiera from source
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Apart from the Lumiera source code, you'll require additional packages to build
|
|
Lumiera. These additional packages are of two kinds:
|
|
|
|
Packages normally available with your distribution::
|
|
for a Debian based system (including Mint, Ubuntu and similar flavours),
|
|
you should be able to install the necessary dependencies with the command
|
|
+
|
|
------------------------------------------------------------
|
|
sudo apt-get install build-essential scons git-core valgrind intltool \
|
|
libboost-dev libboost-program-options-dev libboost-regex-dev libboost-filesystem-dev \
|
|
libgavl-dev libgtkmm-2.4-dev librsvg2-dev libxv-dev
|
|
------------------------------------------------------------
|
|
Packages not normally part of your distribution::
|
|
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 them yourself:
|
|
|
|
- *NoBug* -- a diagnostics library
|
|
+
|
|
------------------------------------------------------------
|
|
git clone git://git.pipapo.org/nobug
|
|
cd nobug
|
|
autoreconf -i
|
|
mkdir build && cd build
|
|
../configure
|
|
make
|
|
sudo make install
|
|
------------------------------------------------------------
|
|
- *GDL* -- a window docking library footnote:[GDL _is_ usually available
|
|
through the standard package manager, albeit in a GTK-3 based version;
|
|
since we haven't managed to port our GUI to GTK-3, we're sticking to a
|
|
rather ancient version of the Gnome Docking Library for now]
|
|
+
|
|
------------------------------------------------------------
|
|
git clone git://git.lumiera.org/debian/gdl
|
|
cd gdl
|
|
./configure
|
|
make
|
|
sudo make install
|
|
------------------------------------------------------------
|
|
|
|
Start the Lumiera build process::
|
|
------------------------------------------------------------
|
|
cd LUMIERA
|
|
scons
|
|
------------------------------------------------------------
|
|
|
|
If Lumiera is built correctly on your system, you should be able to shoot up
|
|
the Lumiera GUI with the command
|
|
------------------------------------------------------------
|
|
target/lumiera
|
|
------------------------------------------------------------
|
|
Congratulations! Now we can move on to making contributions.
|
|
|
|
|
|
|
|
Contribute 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 committing, 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
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
The mailing list is the central information hub of the project.
|
|
If you're stuck in some way or the other, or need further explanation,
|
|
don't hesitate to ask. When it comes to more informal exchange, the IRC
|
|
is a good place too. If none of the core devs is online, just drop a message
|
|
to the mailing list, and we'll arrange a schedule for an informal meeting.
|
|
Besides, the Lumiera community generally meets on the second Thursday of
|
|
each month at 20:00 UTC on IRC. All are more than welcome to join and
|
|
to contribute to the discussions there.
|
|
|
|
-> contact information link:{l}/project/contact.html[Mailing List & IRC]
|
|
|
|
''''
|
|
|
|
|
|
Lumiera: Areas for possible contribution
|
|
----------------------------------------
|
|
|
|
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. Especially, our custom style sheet needs to be ported
|
|
- we urgently need conceptual (non-coding) contributions
|
|
|
|
* work out a coherent handling concept, in accordance with model and core
|
|
* we need a concept for key bindings and focus
|
|
* we need a concept for integration with control surfaces
|
|
* we need a concept for pen based handling
|
|
|
|
|
|
Proc Layer::
|
|
- external connection systems
|
|
|
|
* investigate good ways to output video, both in-window and full screen.
|
|
Especially, the integration is what counts: it should be a well maintained
|
|
library, and play well with our intended framework and memory management.
|
|
* expand on the work done for ALSA and Jack audio.
|
|
* expand on the work done for LADSPA / L2. Make Lumiera a host for these plugin systems
|
|
* investigate how to discover sound card properties. Develop a concept how to describe
|
|
these in a generic fashion, independent of the concrete library used for output.
|
|
The purpose is to allow binding with the structure of the session model
|
|
|
|
- memory management
|
|
|
|
* expand on the work done for a pooling small objects allocator.
|
|
* develop a backend for our various allocation schemes to use this allocator.
|
|
|
|
- help with the C++11 transition
|
|
- Command system at the GUI interface
|
|
|
|
* expand on the work done for generic commands
|
|
* implement a command dispatcher to allow blocking and queuing of commands
|
|
* develop a scheme how to code the GUI commands in practice
|
|
|
|
- implement a symbol table for the `lib::Symbol` datatype
|
|
- provide the foundation for symbolic rules and script bindings
|
|
|
|
* expand on the work done for symbolic and hash references
|
|
* implement a hierarchical registration service to support per-type symbol namespaces
|
|
* integrate (and maybe adapt or overhaul) the existing session (placement) index and
|
|
asset registry into this new symbol binding system
|
|
|
|
- evolve and implement our stream type system
|
|
|
|
|
|
/////////////////
|
|
Backend::
|
|
|
|
TODO: where to contribute to the backend??
|
|
|
|
/////////////////
|
|
|
|
|
|
|
|
Website and infrastructure::
|
|
- authoring support scripts
|
|
- implement the new website design
|
|
- help with our continuous integration setup
|
|
|
|
|
|
|
|
''''
|
|
''''
|
|
|
|
Do you have any further ideas? Please speak up on the mailing list or on IRC.
|
|
Such are always welcome.
|
|
|