/doc/development/contribute.rst

https://gitlab.com/vote539/ase · ReStructuredText · 118 lines · 80 code · 38 blank · 0 comment · 0 complexity · f0ef5830f717177e30f549f31fba3081 MD5 · raw file

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