LUMIERA.clone/doc/user/tutorials/contributing.txt

Contributing to Lumiera
=======================
:Author: Benny <Benny.Lyons@gmx.net>
:Date: Oct 2013 · Nov 2025
:toc:


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.


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
https://www.kernel.org/pub/software/scm/git/docs/gittutorial.html[basic Git tutorial at Kernel.org]. +
For more specific questions, you might consult a https://git-scm.com/docs[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 g++ git pkgconf scons intltool \
libboost-dev libboost-program-options-dev libasound2-dev libgavl-dev \
libgtkmm-3.0-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.lumiera.org/debian/nobug
cd nobug
autoreconf -i
mkdir build && cd build
../configure
make
sudo make install
------------------------------------------------------------
  - the *libGDL* with **mm**-bindings -- a window docking library footnote:[
      GDL is compatible with GTK-3 and was available through the standard package manager,
      but was orphaned in 2021. Since it is currently a prerequisite for building Lumiera,
      we maintain a clone of the original repository and a Debian package on Lumiera.org.
      This is relevant both for
      https://git.lumiera.org/?p=debian/gdl;a=summary[libGDL (3.40) +git://git.lumiera.org/debian/gdl+]
      and the
      https://git.lumiera.org/?p=debian/gdlmm;a=summary[GDL C++ bindings (3.7.3) +git://git.lumiera.org/debian/gdlmm+].
    ]

    * first you have to build libGTL itself...
+
------------------------------------------------------------
git clone git://git.lumiera.org/debian/gdl
cd gdl
git checkout master
./autogen.sh
make
sudo make install
------------------------------------------------------------

     * then followed by building the C++ bindings...
+
------------------------------------------------------------
git clone git://git.lumiera.org/debian/gdlmm
cd gdlmm
git checkout master
./autogen.sh
make
sudo make install
------------------------------------------------------------


Start the Lumiera build process::
------------------------------------------------------------
cd LUMIERA
scons -j#
------------------------------------------------------------

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: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:/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.
- 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


Steam 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.

- 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


/////////////////
Vault::

TODO: where to contribute to the backend / the vault??

/////////////////



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.