This document is meant to get new developers started. It will not go into depth of programming in Julia or working with git, as there are far better resources on these things online.
Once you open a pull request on GitHub you will receive feedback, comments, and questions on GitHub. So please pay attention to your GitHub notifications.
- If you encounter error messages after rebasing to the current master, chances are that some dependencies need upgrading. Please first try whether executing
]upgets rid of your errors.
- Please have a look at the Developer Style Guide and the Design Decisions. Adhering to the style guide makes reviewing code easier for us, and hence your new feature can be merged faster.
- Let us know what you are working on early:
- You can open a draft pull request on GitHub right at the beginning of your work. We are more than happy to look at incomplete prototypes to get an idea of what you are working on. This allows us to assess what kind of problems you might encounter and whether we can mitigate these by making changes to OSCAR.
- Feel free to contact us on Slack.
- Have a look at our community page.
- Please also read our page on Documenting OSCAR code.
- Look at existing code that does similar things to your project to get an idea of what OSCAR code should look like. Try to look at multiple examples.
In general you have to do the following six steps for submitting changes to the OSCAR source:
- Fork the main Oscar.jl repository. For this go to the Oscar.jl GitHub page and click on "Fork" at the upper right.
- Clone your forked repository to your local machine. If you have set up ssh access you can do this in the following way:
git clone email@example.com:your_github_username/Oscar.jl
- Create a new branch, usually the naming convention is to use your initials ("yi") and then describe your change, for example:
git checkout -b yi/new_feature git checkout -b yi/issue1234 git checkout -b yi/document_feature
- Edit your source and try out your changes locally (see below). To use your local copy of the sources, start Julia and
If this succeeds, you can enter
using Oscarin Julia and it will use your local copy.
- Once you are done editing, push your branch and open a pull request. It is recommended that you open a draft pull request to the main OSCAR repository as soon as you start working. That way OSCAR developers are aware of work being done and can give feedback early in the process.
- Once you have finished your work, mark your pull request as ready. It will then be reviewed and, probably after feedback and requests for changes, merged.
Alternatively you can call
in Julia. This will create a directory
~/.julia/dev/Oscar. This directory is a git clone of the central OSCAR repository. You can develop your code here, however you will still have to fork OSCAR, as you have no rights to push to the central repository. You can then add your fork as another remote, have a look at the section on rebasing below for hints.
The sources can be found in the
src folder. Please pay attention to the folder structure and choose sensibly where to place your code (when fixing a bug this is probably a minor question).
There are two ways to add tests:
- There are combined tests and examples in the docstrings, namely the
jldoctestblocks. For these have a closer look at Documenting OSCAR code.
- Larger tests and tests that aren't useful examples are in the
testfolder. The main file there is
test/runtests.jlwhich then includes other testfiles.
test_module(x, new::Bool = true)
Run the Oscar tests in the file
x is a string.
x == "all" run the entire testsuite.
The optional parameter
new takes the values
true (default). If
true, then the tests are run in a new session, otherwise the currently active session is used.
For more information on docstrings, please read our page on Documenting OSCAR code. There are two places where documentation can be added:
- In the docstrings above the functions in the
- In the documentation files in the
docs/srcfolder. The overall structure is fixed in the file
docs/doc.main. If you create a new file in
docs/src, you will have to add an entry in
In general, 1 is preferred to 2, i.e. any explanation of the functions and objects should go there and the files in
docs/src should remain relatively sparse. Please also pay attention to the documentation section of the Developer Style Guide.
Especially if you will be developing a lot, this can speed up your workflow tremendously.
Revise you can avoid having to restart Julia and reloading OSCAR when editing the code. As a quick summary, first install
using Pkg; Pkg.add("Revise");
From then on do
using Revise, Oscar
whenever you are using OSCAR in Julia.
Working with the development version also entails that the packages
Oscar depends on need to be up to date. Julia can update these packages if you type
]up in the Julia prompt. Many error messages after updating the source can be resolved by simply updating.
Please have a look at the Developer Style Guide to get an overview over naming conventions, code formatting, etc.
To build and test the documentation, please have a look at Documenting OSCAR code.
One way to stay up to date with the current master is rebasing. In order to do this, add the main Oscar.jl repository as a remote, fetch, and then rebase.
git remote add oscar-system firstname.lastname@example.org:oscar-system/Oscar.jl git fetch oscar-system git rebase oscar-system/master
Adding the remote only has to be executed once.