First, thanks for taking the time to contribute. Contributions in any form, such as documentation, bug fix, examples or algorithms, are appreciated and welcome.
We list below some guidelines to help you contribute to the package.
Interactions on this repository must follow the Julia Community Standards including Pull Requests and issues.
If your question is related to Julia, its syntax or tooling, the best places to get help will be tied to the Julia community, see the Julia community page for a number of communication channels (Slack, Zulip, and Discourse being the most active).
For now, the best way to ask a question is to file an issue or reach out to Mathieu Besançon or Sebastian Pokutta. You can also ask your question on discourse.julialang.org in the optimization topic or on the Julia Slack on
#mathematical-optimization, see the Julia community page to gain access.
If you found a bug or want to propose a feature, we track our issues within the GitHub repository. Once opened, you can edit the issue or add new comments to continue the conversation.
If you encounter a bug, send the stack trace (the lines appearing after the error occurred containing some source files) and ideally a Minimal Working Example (MWE), a small program that reproduces the bug.
Contributing to the repository will likely be made in a Pull Request (PR). You will need to:
- Fork the repository
- Clone it on your machine to perform the changes
- Create a branch for your modifications, based on the branch you want to merge on (typically master)
- Push to this branch on your fork
- The GitHub web interface will then automatically suggest opening a PR onto the original repository.
See the GitHub guide to creating PRs for more help on workflows using Git and GitHub.
A PR should do a single thing to reduce the amount of code that must be reviewed. Do not run the formatter on the whole repository except if your PR is specifically about formatting.
The documentation can be improved by changing the files in
docs/src, for example to add a section in the documentation, expand a paragraph or add a plot. The documentation attached to a given type of function can be modified in the source files directly, it appears above the function / type / thingy you try to document with three double quotation marks like this:
This explains what the function `f` does, it supports markdown.
If you fix a bug, one would typically expect to add a test that validates that the bug is gone. A test would be added in a file in the
test/ folder, for which the entry point is
examples/ folder features several examples covering different problem settings and algorithms. The examples are expected to run with the same environment and dependencies as the tests using TestEnv. If the example is lightweight enough, it can be added to the
docs/src/examples/ folder which generates pages for the documentation based on Literate.jl.
Contributions bringing new features are also welcome. If the feature is likely to impact performance, some benchmarks should be run with
BenchmarkTools on several of the examples to assert the effect at different problem sizes. If the feature should only be active in some cases, a keyword should be added to the main algorithms to support it.
Some typical features to implement are:
- A new Linear Minimization Oracle (LMO)
- A new step size
- A new algorithm (less frequent) following the same API.