Ichthyostega
651cf144a5
- comb through the Website, starting at the frontpage - add a **news** entry to confirm this major upgrade step (C++23) - improve the wording in various overview pages - adapt the ''release checklist'' to align it with **git-flow** - reorganise the image folder(s) on the website - the animated beating heart is back ;-)
328 lines
12 KiB
Text
328 lines
12 KiB
Text
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
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
image:{img}/git.png[title="Git"] All files in the Lumiera project are managed by
|
||
https://git-scm.com/[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
|
||
http://localhost:8888/documentation/design/workflow/Verwijlen/index.html[coherent UI handling concept]
|
||
|
||
** 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
|
||
|
||
* expand on the work done for ALSA and Jack audio.
|
||
* expand on the work done for LADSPA / LV2; +
|
||
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.
|
||
|
||
- 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
|
||
|
||
|
||
Current goals of development::
|
||
- achive a link:{ldoc}/design/governance/integration.html[first integration] of the application...
|
||
- https://issues.lumiera.org/report/17[»Focus Topics«] for further development.
|
||
|
||
|
||
''''
|
||
....
|
||
|
||
|
||
|
||
....
|
||
|
||
Do you have any further ideas?
|
||
|
||
Please speak up on the mailing list or on IRC. +
|
||
Such are always welcome.
|
||
|