In short, contribution to JuliaFEM goes in the same way like in other open source
projects, so instructions to contribute follows closely what is described in other
packages. We probably cannot explain the process better than the authors of Julia
themself, so a good starting point is to read from Julia’s documentation
how to make changes to an existing packages.
Documenter.jl to document packages, so it’s also worth of reading coding
There’s a hundreds of tutorials of using
git, so they are also very relevant
reading. Try google with search terms like
If you feel these instruction hard to follow, you can always ask for assistance from our Gitter channel.
In a nutshell, the basic steps for contributing to JuliaFEM are listed below:
Create an account or sign in to GitHub.
Go to Git home page and download the Git installer. Run the installer to get Git on your computer. It is a version control system used by GitHub. To learn its basics, go through this Git tutorial. Another option is to install e.g. SourceTree. Now you should have a
Git Bashin your computer.
Download and install Julia (v0.6+) to your computer. You can get the latest version from here. From Julia README you will find the complete instructions for installing it for your platform.
Go to the JuliaFEM GitHub page. At the top-right corner, press the
Fork-button to fork your own copy of JuliaFEM to your own account.
Clone JuliaFEM from your repository to your computer. Navigate to the folder you want to clone it to, and type the following command (inserting your GitHub username to its place):
git clone https://github.com/your_github_username/JuliaFEM.jl.git
Alternatively, you can clone the package using Julia’s commmand
In the latter case, package will go to somewhat hidden place
Notice, that if you clone repository to some non-standard location, you must make julia aware of the new package location by a modifying
LOAD_PATH. For example, if you have JuliaFEM cloned to
~/repositories/JuliaFEM, you need to
push!(LOAD_PATH, joinpath(homedir(), "repositories")before
If you have already installed JuliaFEM using
Pkg.add, you can simply edit that, but in that case you have to push changes to your forked version as in default you are not having push access to repositories under JuliaFEM organization. Add your fork as remote repository for the JuliaFEM repository on your local computer:
git remote add USERNAME https://github.com/USERNAME/JuliaFEM.jl.git
After that you can push the changes to your fork by
git push USERNAME master.
Make sure you are not having JuliaFEM two times in your system, i.e., one copy in
~/.julia/v0.6/JuliaFEMand other one in
~/repositories/JuliaFEM. If that is the case, you can rename the directory not to keep and after that make Julia aware of JuliaFEM by making for example symbolic link to
~/.julia/v0.6if keeping the copy located in outside of Julia’s package directory or add non-standard path to
LOAD_PATHas explained above.
You can now navigate to JuliaFEM in the folder you chose at step 5. There you’ll find the same contents as you see in your GitHub JuliaFEM repository. Now, locate the file you want to modify, open it with your desired text editor, make the changes and save the new version. If you type
git status, you’ll see that the files you’ve created or modified are listed under
Add the files you want to update to the staging area by typing
git add <file1> <file2>.... If you type
git status, you’ll see that the files added to the staging area are listed under
Changes to be committed. This process also supports wildcard symbols. If you want to remove a file from the staging area, type
git reset <file>.
To store the staged files, commit the files to your repository and add a description message by typing
git commit -m "your_message_here". The message should describe the changes that were made.
When you are happy with the commits and want to update them to your repository, type
git push origin master.
Go to your GitHub JuliaFEM repository. You’ll notice that the commit you have made and pushed is now visible above the JuliaFEM file branch. If you click the
latest commitlink, you can see the changes made to the file. Finally, click
Pull requestto create a pull request of the commits you’ve made, so that other contributors can review it.
If other contributors ask you to make changes to your pull request, just repeat steps 6-9. Your commits will be updated to your original pull request. Do this until everyone is satisfied and your pull request can be merged to the master branch.
There’s also some GUI apps to use git if you don’t feel command line comfortable. For OSX and Windows a good application is SourceTree, for Linux, maybe SmartGit will work. GitHub has also desktop application.
Details of contibuting to JuliaFEM
Travis-CI runs PkgTestSuite.jl to verify the quality of code, so it’s good idea to run that on own local computer before doing pull request. PkgTestSuite tests that all tests pass. Furthermore, some more tests are performed like testing that all source files have proper licence header and no tabulators has been used in code. If you have already done pull request, you can inspect from travis if the build fail to find out the cause of failure.
Don’t use utf-8 characters in program code
We are not using utf-8 characters. See issue #18.
Supported Julia versions
We support Julia versions 0.6+. See issue #26.
Use only pull requests, never push to master
See issue #29. This
ensures peer review check for contributors and hopefully will decrease the
number of merge conflicts. Before making the pull request run all tests:
julia> Pkg.test("JuliaFEM") at REPL or
julia test/runtests.jl at
New technology is recommended to be introduced through notebooks
See issue #12. Idea is to introduce new technology as a notebook for the very beginning. Then when it’s get mature the notebook will serve functional test for the matter. All notebooks will be included as examples to the documentation.
Write unit tests for a package
See issue #27. We believe into Test Driven Development (TDD), thus 100 % test coverage is the ultimate goal.
JuliaFEM.jl is using Logging.jl
See issue #25. We have
written a test to check all sources in src folder to find any print statements.
Logging.jl instead of
println(). No use of
println() is allowed in code.
We use 4 spaces like in Python. See issue #5.
Write docstrings for function
Docstrings help people to understand how functions works and they are a crucial part of quality code. See issue #. For a good introduction how to write good docstrings, see the official Julia documentation about docstrings.
We use MarkDown syntax to document projects. Information how to write markdown format is described on internet. Here is markdown cheatsheet. See issue #49.
This is not (yet) strict requirement, but try to keep line width max 80 characters, like in Python.
For performance critical functions use @inferred
See issue #90