How to contribute
=================

If you want to help out with Cadabra, or think you can contribute a
useful add-on package or perhaps just a sample notebook or a bit of
documentation, you are more than welcome! Even just dropping us a
note with some details about what computations you do with Cadabra
is a useful contribution, and helps to get a better idea of what
people expect from the software. 

Below are some tips on how to get started contributing to Cadabra. For
any questions, please post in the [questions and answers][1] forum or
get in touch directly via [email][2]


Get familiar with the software
------------------------------

The first thing to do is to get familiar with how the software works,
by playing with the [tutorials][3] Details of the software, including
some of the logic that is behind its inner workings, are described in
the [reference guide][4], and documentation is available separately
for all [properties and algorithms][5]. If you get stuck, do not
hesitate to post a question on the [questions and answers][1] site. If
you want to contribute at the level of the C++ core, or if you are
simply interested in how things work behind the scenes, you will find
the [doxygen][6] documentation useful.


Identify something to work on
-----------------------------

Most likely you will have used (or will have tried to use) Cadabra for
a concrete project, and found that you see room for improvement. This
can be as simple as reporting a bug, perhaps even fixing it, or adding
a tutorial or other documentation, providing add-on functionality in
the form of packages, or helping with the core. We are also always
interested to hear about issues installing Cadabra on new systems.


Setup your development environment
----------------------------------

Contributions in any form are welcome, but if you want to submit
substantial code contributions, it is useful to get familiar with the
git version control system. This is used to track software changes
over time and to effectively manage contributions from different
authors. We also utilise [github][7], a web interface to git,
extensively and use it for communication, issue tracking, merging
patches (pull requests) and so on. Check out the source code from
there and follow the instructions on how to build it.


Code conventions
----------------

To generate debug output, we use the [dbg][8] facility. To turn this
on for a particular source file, comment out the `DBG_MACRO_DISABLE`
definition at the top. You will then get nicely formatted debug output
while running.

Code is formatted using tabs for indentation, K&R style braces,
with some fine-tuning. All is taken care of by `make format` in the
top-level directory, which runs through the entire source tree and
does a reformat using `astyle`.


Documentation
-------------

We have tutorials, manual pages and reference documentation. In
addition, there are user-contributed notebooks. In this sense, we try
to follow [divio][9]. Contributions to all of these parts of the
documentation are welcome.


[1] https://cadabra.science/qa/
[2] mailto:info@cadabra.science
[3] https://cadabra.science/tutorials.html
[4] https://cadabra.science/help.html
[5] https://cadabra.science/man.html
[6] https://cadabra.science/doxygen/html/
[7] https://github.com/kpeeters/cadabra2
[8] https://github.com/sharkdp/dbg-macro
[9] https://www.divio.com/blog/documentation/