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.
Check out the paper presenting the package for a high-level overview of the feature and algorithms and the documentation for more details.
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.
"""
function f(x)
# ...
endIf 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 runtests.jl.
The 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.
We try to follow the Julia documentation guidelines.
We run JuliaFormatter.jl on the repo in the way set in the .JuliaFormatter.toml file, which enforces a number of conventions.
This contribution guide was inspired by ColPrac and the one in Manopt.jl.