WIP: "contributing"-tutorial, errors corrected, new sections.
Some obvious typos were corrected. Other material improved. The section on Git was considerably improved. An entirely new section on Git was added, but which contains some previous material on git. The reason for adding a new section on Git was I though it better to have one single place where someone new to Git and Lumiera could read a simple recipe-type explanation on how to retrieve source code, make changes and then push the changes. All information necessary including Git, links, etc should be on this page, no following liknks. In fact there is no real _new_ information here that isn't to be found somewhere else. The point being that _all_ information necessary to ge someone up and going is located on one page. For this reason, I added information on the mailing list and IRC; again, all essential information in how to contribute to Lumiera, the title ang goal of this page. There might be stuff missing here, so please add, but do not make this page too long. That tends to scare people, in fact, someone might just like to shorten my contributions here, that would be good!
This commit is contained in:
parent
b548abd01e
commit
23040e9c7b
1 changed files with 96 additions and 21 deletions
|
|
@ -3,41 +3,91 @@ Contributing to 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
|
||||
Lumiera project communication and contributing to Lumiera.
|
||||
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
|
||||
mailing list.
|
||||
|
||||
|
||||
a powerful tool
|
||||
that not only
|
||||
|
||||
|
||||
which is a distributed
|
||||
source code management system.
|
||||
|
||||
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 right'' is necessary; you can
|
||||
start right away and present your first results in the _mob repository_.
|
||||
contributing very low: No formal ``commit permission'' is necessary; you can
|
||||
start right away and present your first results to the _mob repository_.
|
||||
|
||||
For starters, follow the
|
||||
|
||||
|
||||
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] for using Git, notably the following parts:
|
||||
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.
|
||||
|
||||
|
||||
Letting People Know Who You Are
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
------------------------------------------------------------
|
||||
$ git config --global user.name "Your Name Comes Here"
|
||||
$ git config --global user.email you@yourdomain.example.com
|
||||
------------------------------------------------------------
|
||||
|
||||
If you followed the link:building.html[building-lumiera tutorial], you created
|
||||
already a local clone of the Lumiera repository. So you are ready to go,
|
||||
you can edit build and commit your changes to the lumiera code locally in
|
||||
your cloned repository. Please commit frequently, do small commits which
|
||||
fix/improve only one single thing and use meaningful commit messages.
|
||||
Obtaining Lumiera Code
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
------------------------------------------------------------
|
||||
$ git clone git://git.lumiera.org/LUMIERA
|
||||
------------------------------------------------------------
|
||||
|
||||
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
|
||||
link:building.html[building-lumiera tutorial] on how to obtain all packages to
|
||||
build Lumiera.
|
||||
|
||||
|
||||
Contributing
|
||||
~~~~~~~~~~~~
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
------------------------------------------------------------
|
||||
$ cd .../doc/users/tutorials
|
||||
$ git add contributing.txt
|
||||
$ git commit contributing.txt -m "Corrected a grammatical error in section Git"
|
||||
------------------------------------------------------------
|
||||
|
||||
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 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).
|
||||
The line following your one line summary should be blank. Then on the third
|
||||
line, you can begin your exposition on your changes.
|
||||
|
||||
|
||||
Publishing Your Contribution
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Check that you didn't break anything, by running the testsuite.
|
||||
|
||||
|
|
@ -47,7 +97,32 @@ Finally you can push your changes to the lumiera server to 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. Then you notify the
|
||||
other devs on the mailinglist and they may merge your code into the mainline.
|
||||
This creates a new branch 'YOURNAME' on the mob repository.
|
||||
|
||||
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
|
||||
your code into the main project line.
|
||||
|
||||
|
||||
Lumiera Communication Channels
|
||||
------------------------------
|
||||
|
||||
|
||||
The 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_.
|
||||
|
||||
All are more than welcome to join and to contribute to the discussions there.
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue