contents
This document is aimed at helping newcomers to contribute.
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.
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.
One very useful place to begin with learning Git is the
basic Git tutorial at Kernel.org.
For more specific questions, you might consulte a 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.
$ git config --global user.name "Your Name Comes Here"
$ git config --global user.email you@yourdomain.example.com$ git clone git://git.lumiera.org/LUMIERAIf 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 building-Lumiera tutorial for a more in-depth description of the necessary steps. The next section gives a brief summary of this process.
Apart from the Lumiera source code, you’ll require additional packages to build Lumiera. These additional packages are of two kinds:
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-3.0-dev libgdl-3-dev librsvg2-dev libxv-devthere 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
mm-bindings for GDL — a window docking library
[GDL itself is
available through the standard package manager, in a version compatible to GTK-3.
What is not yet available are the corresponding C++ bindings gdlmm-3]
git clone git://git.lumiera.org/debian/gdlmm
cd gdlmm
./configure
make
sudo make installcd LUMIERA
sconsIf Lumiera is built correctly on your system, you should be able to shoot up the Lumiera GUI with the command
target/lumieraCongratulations! Now we can move on to making contributions.
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 emacsThen 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.
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/YOURNAMEThis creates a new branch YOURNAME on the mob repository.
Check that indeed your changes are public by visiting
the Git-Web:
The lumiera/mob repository should indicate
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.
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 Mailing List & IRC
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.
the stylesheet has been roughly ported to GTK-3, but needs a lot more polishing
we urgently need conceptual (non-coding) contributions
work out a coherent UI 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
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.
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
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
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.