matlab2tikz is in constant motion and there are things that it can't quite handle yet. Sometimes, labels may be misplaced or matlab2tikz may abort with an error message and not plot anything at all. Also, maybe it can't handle the fancyPlottingRoutine() of yours quite yet, but you really really need high-quality figures for the deadline at midnight?

If the latest matlab2tikz release is a while ago and your see a bunch of new commits in our development branch that have not been incorporated into the master branch (i.e. the releases on FileExchange), your best guess is to get the latest code from our develop branch on GitHub and see if it already works there.

If not, it'd certainly be helpful to point out what doesn't work. You can then best create an issue ticket. This way, you can be sure that all developers see your problem/suggestion and it is not going to drown in any e-mail inbox.

When pointing out an issue, it's most useful to provide a simple plot that demonstrates what goes wrong.

• Don't overload the figure. If some labels are misplaced, create a figure that has a misplaced label, and leave the colormapped surf-contour 3D plot with all bells and whistles out. This makes it easier to find out what the problem is and come up with a fix.
• Only submit the MATLAB (".m") file. The matlab2tikz command line output and the resulting LaTeX file can be reproduced with the MATLAB file already (unless you have strong indications that the bug is some intricate TikZ/pgfplots problem).
• Please clearly indicate which version of MATLAB/Octave and matlab2tikz you are using. If you are using git to manage matlab2tikz, please indicate the commit hash (or the output of git describe in the matlab2tikz directory).

If you have an idea of how to add functionality to matlab2tikz, or you see a bug and are motivated enough to fix it, we are happy to review and include your changes.

There are different ways of how to contribute your code, here are a few (starting with the recommended approach). Note that, in any case, a small test case that demonstrates the previous bad and now good behavior is always helpful.

• Fork matlab2tikz on GitHub, add your changes, and send a pull request. Please follow the recommended workflow.

• Create a patch from git directly and send it using an issue ticket or by e-mail. The workflow for this approach is explained here.

• Create a patch with diff. As opposed to the previous two methods that your name will not appear in the git log.

• If the change is trivial, send us a snippet through an issue ticket and let us know where it should be included.

To use the test suite yourself, follow the instructions in our testing README.

If you have discovered and fixed a bug in matlab2tikz, and you'd like to be sure that other contributers will not destroy the functionality that you added, then you may want to think about adding a test function for your case.

To this end, edit the file test/suites/ACID.m and add a routine at the end that produces a MATLAB(R) plot at the end of the file (please take a look at some of the other tests to see how such a function should behave). Note that you must not call the figure function from within your test function.

Also, append a handle of this function to the list of handles at the beginning of the file. Now, your function is included into the test suite.

If you have access to multiple versions of MATLAB and Octave, it is also advised to test your code in MATLAB 2014a (or slightly older), MATLAB 2014b or newer and the latest Octave version.

Since we want to run everything in a more-or-less democratic way, there are a few conventions that we try to follow to keep everybody happy. This is mainly of interest for the developers of matlab2tikz.

Next to our users, we have 3 special kinds of people.

• Associate Developers are people we want to acknowledge for their work on matlab2tikz. Most of the time, they have just started writing code for matlab2tikz (or they have written code for matlab2tikz in long forgotten times). Once you've submitted a pull request, you can expect to be invited to join this team.
• Developers are people who have contributed a significant amount of work to matlab2tikz. The advantage of being a developer is that you are given the responsibility to merge pull requests of other people. If you have illustrated that you are a great asset for this project (e.g. we have merged your many pull requests), you can expect an invite for this team.
• Owners are here to keep the project moving in the right direction and are responsible of inviting you to become an (associate) developer. If we do forget to bump your status, please feel free to contact us!

In our issue reports (and feature requests), we have a few Labels that describe the nature and status of each issue report. Please add the appropriate labels if you stumble across an issue that has none.

If a new issue is reported and you feel that you can help to understand the problem or even help come to a solution, go ahead an join the conversation.

There are a few labels that deserve special attention here:

• discussion: indicates that discussion is strongly encouraged. If you have an opinion or a relevant idea: please speak up!
• work-in-progress indicates that work is underway and that some people are tackling the issues. If you want to help out, make sure you communicate this.

Next to the work-in-progress label, issues can be assigned to someone (but they don't have to be). Such an assignment basically means that the next action should be taken by that person. If you assign yourself, you signal your intent "I will take care of this".

Pull requests (PRs) are a special kind of issue report in that they contain new code for the project. Please follow the guidelines below.

• If the PR is meant to fix a certain issue, make sure you link to that issue, possibly even with a keyword such as "closes" to close the issue automatically after the PR is merged.
• When you file a PR as a developer, please indicate how you have tested the code (what MATLAB/Octave versions, OS, ...).
• Everybody (users, associate developers, developers, ...) is welcome to review a PR.
• Review the code in the PR thoroughly. This can either be done commit-per-commit or for the whole PR at once. The latter is faster and easier to keep an overview of the discussion. The former is mainly interesting if you wish to follow the train-of-thought.
• All PRs should be merged into develop! Only owners will file PRs against "master" in preparation of a new release.
• Wait for the automatic build to finish and do not merge a broken build. If the build is broken, the test results should be inspected and an appropriate action should be indicated (e.g. "fix hashes because the new output is better than the old one").
• Never merge a PR with the "do-not-merge" label attached: it indicates there is still work to be done.
• A pull request should be approved by at least one (other) developer before it is merged. You can indicate your approval by posting :+1: (:+1:) to the PR (not a single commit!).
• If you want to reject a PR, please do so in a respectful and polite way: at least state why you think it should not be merged.
• Only merge a PR if all suggested improvements have been addressed and a consensus has been reached on all points.