ReStructuredText | 118 lines | 80 code | 38 blank | 0 comment | 0 complexity | f0ef5830f717177e30f549f31fba3081 MD5 | raw file
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 email@example.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 firstname.lastname@example.org: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.