/doc/development/contribute.rst

  1=================
  2How to contribute
  3=================
  4
  5Discussion of ASE development takes place on the :ref:`ase-developer
  6<mailing_lists>` mailing list and on the #ase IRC channel on freenode.
  7
  8We welcome new developers who would like to help work on improving
  9ASE.  If you would like to contribute, you should first tell us what
 10you want to work on.  Use the mailing list for that.
 11
 12
 13GitLab repository
 14=================
 15
 16All work on the source code takes place on https://gitlab.com using git_.
 17
 18.. _git: https://git-scm.com/
 19
 20
 21The first steps as a developer
 22------------------------------
 23
 24* register as a user on https://gitlab.com
 25* Find and/or change your user-name in your account setting. You will need it.
 26* follow directions on https://gitlab.com/help/ssh/README for how to generate
 27  and add your own public ssh-key
 28* go to https://gitlab.com/ase/ase and fork the project so that you
 29  get your own GitLab repository to play with.
 30
 31You will now have a fork situated at https://gitlab.com/your-user-name/ase
 32
 33
 34Making small changes
 35--------------------
 36
 37Say you want to fix a typo somewhere.  Here are the steps to do that:
 38    
 39* go to https://gitlab.com/your-user-name/ase
 40* click "Files" and find the file you want to change
 41* click "Edit" and fix the typo
 42* click "Merge Requests" and add your change from the master branch
 43    
 44At this point someone will take a look at your change and merge it to the
 45official repository if the change looks good.
 46
 47
 48Larger changes
 49--------------
 50
 51.. highlight:: bash
 52
 53For larger changes you will want to work with the files on your local
 54computer.  Here are the initial steps:
 55    
 56* Upload your public SSH-key to GitLab if you haven't done it
 57* clone the repository to your computer::
 58    
 59      $ git clone git@gitlab.com:your-user-name/ase.git
 60
 61  where ``your-user-name`` is your GitLab user name
 62
 63It's a good idea to make a local branch for your work::
 64    
 65    $ cd ase
 66    $ git checkout -b myfix  # checkout new branch
 67
 68You can learn the git basics in several places, e.g.
 69http://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository
 70    
 71Edit, test, stage and commit your changes::
 72    
 73    $ cd ase
 74    $ idle atoms.py  # use your favorite text editor here
 75    $ cd ..
 76    $ python setup.py test
 77    $ git diff  # print difference
 78    $ git status  # print what is modified and/or staged and recommended action
 79    $ git add ase/atoms.py  # stage atoms.py for commit
 80    $ git status
 81    $ git commit -m "Fixed bug"  # commit changes into your local branch copy
 82
 83Push your changes to your repository::
 84    
 85    $ git push --set-upstream origin myfix
 86
 87and create a Merge Request on GitLab at https://gitlab.com/your-user-name/ase.
 88
 89If you want to start working on something new, you should switch to your
 90master branch, pull from the official repository and branch again::
 91    
 92    $ git checkout master
 93    $ git remote add official git@gitlab.com:ase/ase.git  # do this once only
 94    $ git pull official master
 95    $ git checkout -b newstuff
 96
 97You can use ``git remote -v`` to see which repositories you have
 98registered locally.
 99    
100Code review
101===========
102
103Before you start working on a Merge Request, *please* read our
104:ref:`python_codingstandard`.
105
106Hopefully someone will look at your changes and give you some
107feedback.  Maybe everything is fine and things can be merged to the official repository right away, but there could also be some more work to do like:
108
109* make it compatible with all supported Pythons (see
110  :ref:`download_and_install`).
111* write more comments
112* fix docstrings
113* write a test
114* add some documentation
115
116This code review loop is not something we have invented to prevent you from
117contributing - it should be viewed as an opportunity for you to learn how to
118write code that fits into the ASE codebase.