ichthyo/LUMIERA.clone
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

DOC: rewrite and improve the 'contributing' tutorial; a Git 'mini HOWTO'

Browse source
This commit is contained in:
Benny 2013-10-10 23:22:21 +02:00 committed by Ichthyostega
parent 6822a9e2fb
commit bc185742aa
1 changed files with 199 additions and 42 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

241
doc/user/tutorials/contributing.txt
View file

@ -1,29 +1,53 @@
Contributing to Lumiera
=======================
Contributing to +Lumiera+
=========================
All files in the Lumiera project are managed by *Git*. Although *Git* was
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
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
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
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_.
Git: Lumiera Essentials
-----------------------
One very useful place to begin with using Git is the following:
http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html[basic
instructions]. In particular, the following parts:
http://gitref.org/
instructions]. In particular, the following parts: http://gitref.org/
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.
@ -37,32 +61,102 @@ $ git config --global user.name "Your Name Comes Here"
$ git config --global user.email you@yourdomain.example.com
------------------------------------------------------------
Obtaining Lumiera Code
~~~~~~~~~~~~~~~~~~~~~~
Obtaining +Lumiera+ Code
~~~~~~~~~~~~~~~~~~~~~~~~
------------------------------------------------------------
$ git clone git://git.lumiera.org/LUMIERA
------------------------------------------------------------
If everything goes ok, you should have the Lumiera source code. However, you do
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. Please refer to the
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.
build +Lumiera+.
Contributing
~~~~~~~~~~~~
Building +Lumiera+
~~~~~~~~~~~~~~~~~~
So you are ready to go, you can edit and commit your changes to the
lumiera code locally in your cloned repository. Please commit frequently, do
small commits which fix or improve only one single thing and try to use
meaningful commit messages.
------------------------------------------------------------
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_.
Here's how to add your changes to Git:
Once you've saved this file, you'll want to record your modifications to you
local Git repository:
------------------------------------------------------------
$ cd .../doc/users/tutorials
@ -70,28 +164,43 @@ $ 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
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
requiring you to enter your comments. Enter, as your first line, a one line
summary of less than 80 characters in length (some applications use this line
for various purposes and longer entries tend to cause difficulties).
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 on your changes.
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 to the 'mob' repository:
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
@ -103,26 +212,74 @@ Check that indeed your changes are public by visiting
http://www.lumiera.org/gitweb [http://www.lumiera.org/gitweb]. The lumiera/mob
repository should indicate 'right now' as its _Last Change_ entry.
Thereafter, notify the other developers on the mailinglist and they may merge
Thereafter, notify the other developers on the mailing list and they may examine
your code into the main project line.
Lumiera Communication Channels
------------------------------
+Lumiera+ Communication Channels
--------------------------------
The Mailing List
~~~~~~~~~~~~~~~~
Mailing List
~~~~~~~~~~~~
------------------------------------------------------------
lumiera@lists.lumiera.org
------------------------------------------------------------
IRC Meetings
~~~~~~~~~~~~
The Lumiera community generally meets on the second Wednesday of each month at
20:00 uucp on: _freenode #Lumiera_.
The +Lumiera+ community generally meets on the second Wednesday of each month at
20:00 uucp 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.