Introduction for new developers
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.
- If you are planning to implement a new feature from scratch, please also read Adding new projects to experimental.
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 edit process
Editing the source
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.
Tests that rely on random values should use
Oscar.get_seeded_rng, which will return a seeded random number source, and pass this to any functions that need random values. The code may also directly create and use such a random source. The current seed will be printed at the beginning of the testsuite, it is fixed to 42 in the CI. It can be changed by setting
ENV["OSCAR_RANDOM_SEED"] (for the testsuite running in a separate process) or by using
Oscar.set_seed! (for the current session, e.g.
test_module(file::AbstractString; new::Bool = true)
Run the Oscar tests in the file
file may be a path.
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 experimental modules, use
Return a new random number generator object of type MersenneTwister which is seeded with the global seed value
Oscar.rng_seed. This can be used for the testsuite to get more stable output and running times. Using a separate RNG object for each testset (or file) makes sure previous uses don't affect later testcases. It could also be useful for some randomized algorithms. The seed will be initialized with a random value during OSCAR startup but can be set to a fixed value with
Oscar.set_seed! as it is done in
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.
Give gh a try
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.
Ask OSCAR Related Questions in the OSCAR Slack.
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.
Building the documentation
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.