1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
# Contributing guide for Gregorio
## Reporting an issue
You can report a bug and request a new feature on the [bug tracker](https://github.com/gregorio-project/gregorio/issues).
Please search for existing issues before reporting a new one.
Please do not use the issue tracker for personal support requests, instead use the mailing-list (https://gna.org/mail/?group=gregorio) or IRC: #gregorio on freenode.
### Report a bug
When you report a bug, please provide the following information:
* version of Gregorio
* a minimal example (gabc or gabc+tex if relevant) showing the bug
* a screenshot of the wrong result
* a precise description (if possible with a picture) of the expected output
### Request feature
When requesting a feature, please provide the following informations:
* a minimal example (gabc or gabc+tex) that currently doesn't work, but would
if the feature was done
* a precise description (if possible with a picture) of the expected output
## Contributing code
### Development environment
It is not currently possible to compile Gregorio under Windows. The build requirements
are the same under GNU/Linux and Mac OSX:
* [git](http://git-scm.com/)
* the [GNU Build System](http://www.gnu.org/software/automake/manual/html_node/GNU-Build-System.html#GNU-Build-System) (often referred to as "Autotools")
* [gcc](https://gcc.gnu.org/) (and associated tools)
* [GNU indent](https://www.gnu.org/software/indent/) (OSX default indent won't work)
* [pylint](http://www.pylint.org/) if you work on Python files
### Coding standards
##### C files
Gregorio targets the following:
* C standard: [ISO C99 Standard](http://en.wikipedia.org/wiki/C99)
* compilers: [gcc](https://gcc.gnu.org/) and [clang](http://clang.llvm.org/)
* architectures: `i586`, `amd64`, `arm`, `arm64`
* under Linux, only [`glibc`](http://www.gnu.org/software/libc/)
* must compile under Mac OSX natively, and under [mingw32](http://www.mingw.org/) and [mingw_w64](https://sourceforge.net/projects/mingw-w64/)
Specific C extensions (GNU extensions, C11, etc.) working for all the above targets are allowed on a case-by-case basis. Patches for other compilers, architectures or libraries can be accepted if they are clean, small and non-intrusive.
Use indent on your code before commiting it, with the `.indent.pro` file in the repository: `indent path/to/my/file.c`.
##### Other files
The rest of the code uses two spaces for indentation of `.tex`, `.lua` and other files, and four spaces for `.py` files.
Gregorio provides an [`.editorconfig` file](../.editorconfig), using an [editorconfig plugin](http://editorconfig.org/#download) for your editor will configure it automatically.
Python files must output no error when inspected by `pylint`.
TeX code must use LuaTeX (more than TeX + eTeX + Omega + PDFTeX) primitives as much as possible, and, when not possible, use code compiling under PlainTeX.
### Tests
When your changes are significant, please provide a test demonstrating the change. See [test documentation](tests/).
### Documentation
If your code has an impact on the user, you must add it to the [changelog file](CHANGELOG.md).
You must also document it in the right places:
* [User manual](doc/) for changes in GregorioTeX
* the [website](http://gregorio-project.github.io/) (in [another repository](https://github.com/gregorio-project/gregorio-project.github.io)) if relevant.
### Git Workflow
The Gregorio team is following the [classical Github workflow](https://guides.github.com/introduction/flow/). More precisely it follows what is sometimes described as "[Gitflow Worflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)", keeping the same branch naming convention.
### Make a pull request
Once you are ready to contribute code:
* fork the repository and checkout your fork
* create a new branch for the pull request you want to make
* commit your changes to this new branch
* make a pull request from this new branch to the relevant branch (usually `develop`)
* the Gregorio developers will inspect and comment your pull request, and finally merge it (or not)
|
