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.
!!! note "Pay attention to your GitHub notifications!" 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
]up
gets 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 git@github.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
]dev /path/to/local/clone/of/your/fork/of/Oscar.jl
using Oscar
in 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
]dev Oscar
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](@ref 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
jldoctest
blocks. For these have a closer look at Documenting OSCAR code. - Larger tests and tests that aren't useful examples are in the
test
folder. The main file there istest/runtests.jl
which 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. Oscar.test_module("something", new=false)
).
Oscar.test_module
Oscar.get_seeded_rng
If a test folder contains a file called setup_tests.jl
it is included
automatically before each file (directly) in this directory. This can be used
to define helper functions that are used in multiple test files, for example
test_save_load_roundtrip
for serialization.
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
src
folder; - In the documentation files in the
docs/src
folder. The overall structure is fixed in the filedocs/doc.main
. If you create a new file indocs/src
, you will have to add an entry indocs/doc.main
.
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.
Use the Revise
package
Using Revise
you can avoid having to restart Julia and reloading OSCAR when
editing the code. As a quick summary, first install Revise
with:
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.
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 git@github.com:oscar-system/Oscar.jl
git fetch oscar-system
git rebase oscar-system/master
Adding the remote only has to be executed once.
- methods,
- methodswith,
- @which,
- @less,
- @edit.