Hi! Thanks for checking out Julia. If you have questions or problems, the Julia dev list is a good place to post them, but you should check out the online Julia docs first. If you have changes you'd like to contribute, you'll need a free GitHub account. (If you're reading this on GitHub, you probably already have one.) You'll also want a working copy of Julia, built from source (you can still contribute with a binary install, but it's harder and not really recommended). In list form, here's what to do to become a contributor:
-
Join the dev list.
-
Create a GitHub account.
-
Build the software and libraries (the first time takes a while, but it's fast after that). Detailed build instructions are in the README. Julia depends on several external packages; most are automatically downloaded and installed, but are less frequently updated than Julia itself.
-
Keep Julia current. Julia is a fast-moving target, and many details of the language are still settling out. Keep your repository up-to-date and rebase your work in progress frequently.
-
Learn to use git, the version control system used by GitHub and the Julia project. Try a tutorial such as the one provided by GitHub.
-
Relax and have fun.
A useful bug report filed as a Github issue provides information about how to reproduce the error.
- Before opening a new Github issue:
- Try searching the existing issues or the
julia-users
mailing list to see if someone else has already noticed the same problem. - Try some simple debugging techniques to help isolate the problem.
- Try running the code with the debug REPL. If you have a source distribution of Julia, you can build your own debug REPL with
make debug
, which produces theusr/bin/julia-debug-basic
andusr/bin/julia-debug-readline
REPLs. - Consider running the debug REPL in a debugger such as
gdb
orlldb
. Obtaining even a simple backtrace is very useful. - If Julia segfaults, try following these debugging tips to help track down the specific origin of the bug.
- Try running the code with the debug REPL. If you have a source distribution of Julia, you can build your own debug REPL with
-
If the problem is caused by a Julia package rather than core Julia, file a bug report with the relevant package author rather than here.
-
When filing a bug report, provide where possible:
- The full error message, including the backtrace.
- A minimal working example, i.e. the smallest chunk of code that triggers the error. Ideally, this should be code that can be pasted into a REPL or run from a source file. If the code is larger than (say) 50 lines, consider putting it in a gist.
- The version of Julia you are using as provided by the
versioninfo()
command. Occasionally, the longer output produced byversioninfo(true)
may be useful also, especially if the issue is related to a specific package.
- When pasting code or output, put triple backquotes (```) around the code block and output block so that Github will format it nicely.
Julia has a built-in package manager based on git. A number of packages across many domains are already available for Julia. Developers are encouraged to provide their libraries as a Julia package. The Julia manual provides instructions on creating Julia packages.
For developers who need to wrap C libraries so that they can be called from Julia, the Clang.jl package can help generate the wrappers automatically from the C header files.
By contributing documentation to Julia, you are agreeing to release it under the MIT License.
Julia's documentation is stored in the doc
directory, and like everything else can be modified using git
. However, for small changes one can also use GitHub's web interface:
- Navigate to https://github.com/JuliaLang/julia
- Click
doc
- If you want to modify an entry in the help for Julia's standard library, click
stdlib
- Pick the file you want to edit (for example,
base.rst
) - Select the
master
branch (if not browsing it already) - Click "Edit"
- Click on the icon that looks like a fullscreen symbol ("Zen" mode)
- Search for the function you want to change
- Make your changes
- Exit Zen mode
- Provide a title, and optionally a longer description of your change
- Submit your change
By contributing code to Julia, you are agreeing to release it under the MIT License.
The Julia community uses GitHub issues to track and discuss problems, feature requests, and pull requests. You can make pull requests for incomplete features to get code review. The convention is to prefix the pull request title with "WIP:" for Work In Progress, or "RFC:" for Request for Comments when work is completed and ready for merging. This will prevent accidental merging of work that is in progress.
Note: These instructions are for adding functionality to the base library. Usually, this is not encouraged, and before doing so, it is essential to discuss the proposed changes or additions on the mailing list or in a github issue. Changing stuff in the base can potentially break a lot of things. Make sure you test your code as described here, together with the latest Julia updates, to avoid problems. Add new code to Julia's base libraries as follows:
-
Add files to the
base/
directory, and tests intotest/
. Often, this may not be necessary and you may be able to add your code to an existing file inbase/
. -
Add any new files to
sysimg.jl
in order to build them into the Julia system image and export necessary symbols inexports.jl
. -
Include your tests in
test/Makefile
andtest/runtests.jl
.
Build as usual, and do make clean testall
to test your contribution. If your contribution includes changes to Makefiles or external dependencies, make sure you can build Julia from a clean tree using git clean -fdx
or equivalent (be careful – this command will delete any files lying around that aren't checked into git). Make sure that Travis greenlights the pull request with a Good to merge
message.
- 4 space indent
- use whitespace to make the code more readable
- comments are good, especially when they explain the algorithm
- 4 space indent
- space between if and ( (if (x) ...)
- newline before opening { in function definitions
- f(void) for 0-argument function declarations
- newline between } and else instead of } else {
- if one part of an if..else chain uses { } then all should
While getting familiar with Julia, remember to check out the docs, keeping in mind that they are searchable. (If you use a script blocker then you'll have to unblock that page.) The source code is an excellent source of examples (and it's mostly pretty approachable). If you're still stumped, post something on the dev list, but you may want to search the archives first to see if there's already been a discussion about what you're stuck on.
-
Julia
- Homepage: http://julialang.org
- Mailing lists: http://julialang.org/community/
- IRC: http://webchat.freenode.net/?channels=Julia
- Source code: https://github.com/JuliaLang/julia
- Git clone URL: git://github.com/JuliaLang/julia.git
- Documentation: http://julialang.org/manual/
- CodeSpeed: http://speed.julialang.org
- Status: http://status.julialang.org
-
Design of Julia
-
Using GitHub