mirror of
https://github.com/JuliaFEM/JuliaFEM.jl.git
synced 2026-08-06 04:21:33 +00:00
Jukka Aho
79 lines
5.6 KiB
ReStructuredText
79 lines
5.6 KiB
ReStructuredText
========================
|
|
Contributing to JuliaFEM
|
|
========================
|
|
|
|
Here are the basic steps for contributing to JuliaFEM:
|
|
|
|
1) Create an account or sign in to `GitHub <https://github.com/>`_.
|
|
|
|
2) Go to `Git home page <http://git-scm.com/>`_ 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 <https://try.github.io/levels/1/challenges/1>`_.
|
|
|
|
3) Install Julia (v0.4+) to your computer. At `Julia readme <https://github.com/JuliaLang/julia/blob/master/README.md>`_ you'll find complete instructions for installing it for your platform.
|
|
|
|
4) Go to the `JuliaFEM GitHub page <https://github.com/JuliaFEM/JuliaFEM.jl>`_. At the top-right corner, press the ``Fork``-button to fork your own copy of JuliaFEM to your repository.
|
|
|
|
5) 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``
|
|
|
|
6) 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 ``untracked files``.
|
|
|
|
7) 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 add all the files to the staging area, just type ``git add .``. If you want to remove a file from the staging area, type ``git reset <file>``.
|
|
|
|
8) 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.
|
|
|
|
9) When you are happy with the commits and want to update them to your repository, type ``git push origin master``.
|
|
|
|
10) 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 commit`` link, you can see the changes made to the file. Finally, click ``Pull request`` to create a pull request of the commits you've made, so that other contributors can review it.
|
|
|
|
11) 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 <https://www.sourcetreeapp.com>`_, for Linux, maybe `SmartGit <http://www.syntevo.com/smartgit/>`_
|
|
|
|
Developing on local machine
|
|
---------------------------
|
|
|
|
To set up ready for development, git clone it to your development directory and make symbolic link to julia package directory:
|
|
|
|
.. code-block:: bash
|
|
|
|
cd ~/dev
|
|
git clone https://github.com/JuliaFEM/JuliaFEM.jl
|
|
cd ~/.julia/v0.4
|
|
ln -s ~/dev/JuliaFEM
|
|
|
|
|
|
Use of UTF-8 characters in program code
|
|
---------------------------------------
|
|
We have decided not to use them. See issue `#18 <https://github.com/JuliaFEM/JuliaFEM.jl/issues/18>`_.
|
|
|
|
Supported Julia versions
|
|
------------------------
|
|
We support Julia versions 0.4+. See issue `#26 <https://github.com/JuliaFEM/JuliaFEM.jl/issues/26>`_.
|
|
|
|
Only pull requests to src folder
|
|
--------------------------------
|
|
See issue `#29 <https://github.com/JuliaFEM/JuliaFEM.jl/issues/29>`_. This ensures peer review check for contributors and hopefully will decrease the number of merge conflicts. Before making the pull request runn all test: either type ``julia> Pkg.test("JuliaFEM")`` at REPL or ``julia test/runtests.jl`` at command line.
|
|
|
|
New technology should be introduced through notebooks
|
|
-----------------------------------------------------
|
|
See issue `#12 <https://github.com/JuliaFEM/JuliaFEM.jl/issues/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.
|
|
|
|
FactCheck.jl is used to write test for the JuliaFEM.jl package
|
|
--------------------------------------------------------------
|
|
See issue `#27 <https://github.com/JuliaFEM/JuliaFEM.jl/issues/27>`_. Use FactCheck.jl package to write the tests. We believe Test Driven Development thus 100 % test coverage is expected.
|
|
|
|
JuliaFEM.jl is using Logging.jl
|
|
-------------------------------
|
|
See issue `#25 <https://github.com/JuliaFEM/JuliaFEM.jl/issues/25>`_. We have written a test to check all sources in src folder to find any print statements. Use Logging.jl instead of println().
|
|
|
|
Code indentation
|
|
----------------
|
|
We use 4 spaces like in Python. See issue `#5 <https://github.com/JuliaFEM/JuliaFEM.jl/issues/5>`_.
|
|
|
|
Function docstrings
|
|
-------------------
|
|
We use numpy documentation style in our functions. See `guide <https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_. See issue `#5 <https://github.com/JuliaFEM/JuliaFEM.jl/issues/5>`_.
|
|
|
|
Documentation
|
|
-------------
|
|
We use restructured text to document this project. Information how to write rst format is described `here <http://sphinx-doc.org/rest.html>`_. See issue `#49 <https://github.com/JuliaFEM/JuliaFEM.jl/issues/49>`_.
|