Skip to content

Latest commit

 

History

History
99 lines (60 loc) · 5.26 KB

CONTRIBUTING.md

File metadata and controls

99 lines (60 loc) · 5.26 KB
Raw

Contributing guide for Gregorio

Reporting an issue

You can report a bug and request a new feature on the bug tracker.

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://groups.google.com/forum/#!forum/gregorio-users) 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:

Coding standards

C files

Gregorio targets the following:

  • C standard: ISO C89 Standard
  • compilers: gcc and clang
  • architectures: i586, amd64, arm, arm64
  • under Linux, only glibc
  • must compile under Mac OSX natively, and under mingw32 and mingw_w64
  • for inclusion with TeX Live, must compile under VisualStudio 2010 for Windows.

Specific C extensions (GNU extensions, 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, using an editorconfig plugin 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. All lines inside macro definitions must end with % to avoid spurious spaces. To check that no line has been forgotten, please check that grep -nE '^(\s|\\(|g|e|x)def)[^%]+$' tex/*.tex tex/*.sty returns only Lua and metapost code or other lines where % is not needed.

Tests

Before submitting a change, please run the tests in gregorio-test against your resulting code.

When your changes are significant, please provide a test demonstrating the change. See test documentation.

If your change breaks some of the existing tests, then please either fix the existing tests or propose the new results be accepted as more "correct" than the old ones.

If you are submitting a new or modified test, please create a new branch in the test repository (preferably with a name which matches the name of the branch your changes are on in the main repository) where you can make these changes. Then create a pull request in the test repository which explains your changes and make sure to reference the corresponding pull request in the main repository. This way those reveiwing your changes can also see what you expect the new test results to be.

Documentation

If your code has an impact on the user, you must add it to the changelog file.

You must also document it in the right places:

Git Workflow

The Gregorio team is following the classical Github workflow. More precisely it follows what is sometimes described as "Gitflow Worflow", 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)