/usr/share/python-ase/doc/development/contribute.rst is in python-ase-doc 3.12.0-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 | .. _contribute:
=================
How to contribute
=================
Discussion of ASE development takes place on the
:ref:`ase-developer <contact>` mailing list and on the ``#ase``
:ref:`IRC channel on freenode <contact>`.
We welcome new developers who would like to help work on improving
ASE. If you would like to contribute, you should first tell us what
you want to work on. Use the :ref:`mailing list <contact>` for that.
GitLab repository
=================
All work on the source code takes place on https://gitlab.com using Git_.
.. _Git: https://git-scm.com/
Proposed git workflow
---------------------
The workflow described here have two elements to them:
1. The guidelines of project git-branches as a whole.
2. The workflow of the individual developer, i.e. the standard operating
procedure when cloning, pulling, pushing etc.
Only the latter will covered at the moment. When the developer team agree
on the former it will be added here too. One comment though:
In general:
* Never work in master branch locally or on GitLab.
* Make a new branch for whatever you are doing. When you are done, push
it to your own repository and make a merge request from that branch in your
repository to official master.
* Do *not* ever merge the main master branch into yours.
The above policy ensures that the master branch means the same thing in all
repositories (official and forks).
You can learn the basics of git in several places:
* `Git Reference <http://gitref.org>`__
* `Pro Git <https://git-scm.com/book/en/v2>`__
* `Introduction to Git with Scott Chacon of GitHub
<https://www.youtube.com/watch?v=ZDR433b0HJY>`__
* `Tech Talk: Linus Torvalds on git
<https://www.youtube.com/watch?v=4XpnKHJAok8>`__
Aliases
-------
These aliases are quite common::
$ git config --global alias.st status
$ git config --global alias.ci commit
$ git config --global alias.co checkout
$ git config --global alias.lol "log --pretty=oneline --abbrev-commit --graph --decorate"
The first steps as a developer
------------------------------
* Register as a user on https://gitlab.com
* Find and/or change your user-name in your account setting. You will need it.
1. Go to gitlab.com/profile
2. Click 'Account' on the left
3. Change your user name to be whatever you want it to be
* Follow directions on https://gitlab.com/help/ssh/README for how to generate
and add your own public ssh-key
* Go to https://gitlab.com/ase/ase and fork the project. The 'fork' button is
to the right of the button with the star and to the left of the 'SSH' button.
Forking the project give you your own personal copy of the project.
You will now have a fork situated at https://gitlab.com/your-user-name/ase
* From here on:
- ``upstream`` refers to git@gitlab.com:ase/ase and refers to the official
repository of the ase project.
- ``origin`` refers to your copy of the ase project located at
git@gitlab.com:your-user-name/ase or https://gitlab.com/your-user-name/ase
For example, ``upstream/master`` refers to the master (i.e., trunk or
development) branch of the official ase project.
* Clone your fork to ``origin`` to your local machine::
$ git clone git@gitlab.com:your-user-name/ase.git
$ cd ase
* Add and track ``upstream`` in your local git (done only once for each local
git repository)::
$ git remote add upstream git@gitlab.com:ase/ase
You can always check the list of remote repositories that you can obtain
code from::
$ git remote -v
And you can check all available branches from the remotes that you are
tracking::
$ git branch -a
Making changes
--------------
Changes and/or additions can be made both directly in GitLab for small
changes (see the :ref:`small changes section<making-small-changes>`) and on a
local branch in your fork. The preferred way using command line on a local
machine is:
1) Ensure that your master branch is in sync with upstream master (since you
should not work in master it's ok).
* Fetch information about heads and references from "upstream" and store it in
local git used in later merges and checkouts::
$ git fetch upstream
* Switch to the local branch called 'master' that is (ideally) identical to
the upstream master branch::
$ git checkout master
$ git merge upstream/master --ff-only
If the previous command fails, then it is safe to simply reset your master
branch to the upstream master branch with the ``--hard`` flag. Use this
flag sparingly, as it is very powerful::
$ git reset --hard upstream/master
If this is first time there would be no need for hard reset, unless some time
has passed since the cloning. Still better safe than sorry.
* It's a good idea to keep also your own origin/master identical to
upstream/master::
$ git push origin master
If this command fails, then you can try again with the ``--force`` flag.
Same as the ``reset --hard`` git command, ``git push --force`` is powerful
and should be used sparingly.
2) Next you can do changes and additions.
* checkout a (new) local branch with a relevant name. I use the commit to
enhance the file contribute.rst as an example::
$ git checkout -b add-contribute-rst
* If you already have this branch from some previous work, but want to do
new work with the same branch name then you should start by resettting it
to current upstream/master both locally and in your GitLab account::
$ git reset --hard upstream/master
$ git push origin add-contribute-rst
* Make your changes. During this stage, you should keep in mind the rule
"Commit early and often." The next three bulleted points should be done
many times during code editing. Each commit should be one "unit" of work.
* Stage the files to be committed using ``git add``::
$ git add contribute.rst
* Check your status::
$ git status
* Commit the staged changes and add commit message. If you can summarize
your changes succinctly, then you can use the command-line syntax::
$ git commit -m "ENH: Add developer workflow guidelines"
But if your changes require explanation via prose, then perhaps you should
just execute ::
$ git commit
And a text editor will appear. Please observe the following guidelines
for writing your commit message. (stolen from
`here <http://chris.beams.io/posts/git-commit/>`_)
The seven rules of a great git commit message
1. Separate subject from body with a blank line
2. Limit the subject line to 50 characters
3. Capitalize the subject line
4. Do not end the subject line with a period
5. Use the imperative mood in the subject line
6. Wrap the body at 72 characters
7. Use the body to explain what and why vs. how
Read the :ref:`commit message
section<writing-the-commit-message>` guidelines for commit messages for
some additional ase-specific information.
* Push commits to your GitLab repository::
$ git push --set-upstream origin add-contribute-rst
* Go to gitlab.com/your-user-name/ase <http://gitlab.com/your-user-name/ase>
and click on '## branches' button (where ## is the number of branches on your
repo)
* Find the branch 'add-contributing-rst' and click '+ Merge Request'
* Provide informative title and more verbose description in the
body of the Merge Request form
* Click the green 'Submit new merge request' button
* For last minutes corrections that you would like to include in the
merge request too, see :ref:`the correction
section<Last-minute-corrections>`
* Wait for feedback from the developer community and address concerns as
needed by adding more commits to the 'add-contribute-rst' branch on your
personal repository and then pushing to your gitlab repository.
* Once the developer community is satisfied with your merge request,
anyone with push access to gitlab.com/ase/ase <http://gitlab.com/ase/ase>
can merge your merge request and it will now be part of the master branch
* After the merge-request is approved, delete the branch locally::
$ git branch -D add-contribute-rst
and on gitlab::
$ git push origin :add-contribute-rst
(output)
To git@gitlab.com:your-user-name/add-contribute-rst
- [deleted] add-contribute-rst
.. _Last-minute-corrections:
Adding corrections to be included in a merge request
----------------------------------------------------
If at this point you would like to make last minute corrections to your
commit (it has happened many times so don't feel too bad) then instead of
closing your own merge request and resubmit a new one you can simply
go into your branch, the one that you requested to merge the first time,
and make the changes, either directly in GitLab, see the
:ref:`small changes section<making-small-changes>`, or locally *before the
merge request has been accepted!*
Since it's the branch that is merged (not just your commit) any changes you
do to that branch will be included should the merge request be accepted::
$ vi contribute.rst
$ git add contribute.rst
$ git commit
$ git push -u origin add-contribute-rst
.. _making-small-changes:
Making small changes
--------------------
Say you want to fix a typo somewhere. GitLab has an editing feature that
can come in handy. Here are the steps to do that there:
* go to https://gitlab.com/your-user-name/ase
* click "Files" and find the file you want to change
* click "Edit" and fix the typo
* click "Merge Requests" and add your change from the master branch
* Unless you actually want to cancel a merge request *Do NOT* click
any buttons that reads 'Close'!
At this point someone will take a look at your change and merge it to the
official repository if the change looks good.
.. _writing-the-commit-message:
Writing the commit message
--------------------------
Commit messages should be clear and follow a few basic rules. Example::
ENH: add functionality X to ase.<submodule>.
The first line of the commit message starts with a capitalized acronym
(options listed below) indicating what type of commit this is. Then a blank
line, then more text if needed. Lines shouldn't be longer than 72
characters. If the commit is related to a ticket, indicate that with
"See #3456", "See ticket 3456", "Closes #3456" or similar.
Describing the motivation for a change, the nature of a bug for bug fixes or
some details on what an enhancement does are also good to include in a commit
message. Messages should be understandable without looking at the code
changes. A commit message like ``MAINT: fixed another one`` is an example of
what not to do; the reader has to go look for context elsewhere.
Standard acronyms to start the commit message with are:
:API: an (incompatible) API change
:BLD: change related to building ase
:BUG: bug fix
:DEP: deprecate something, or remove a deprecated object
:DEV: development tool or utility
:DOC: documentation
:ENH: enhancement
:MAINT: maintenance commit (refactoring, typos, etc.)
:REV: revert an earlier commit
:STY: style fix (whitespace, PEP8)
:TST: addition or modification of tests
:REL: related to releasing ase
Code review
===========
Before you start working on a Merge Request, *please* read our
:ref:`coding conventions`. Please also install a linter!
Hopefully someone will look at your changes and give you some
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:
* make it compatible with all supported Pythons (see
:ref:`download_and_install`).
* write more comments
* fix docstrings
* write a test
* add some documentation
This code review loop is not something we have invented to prevent you from
contributing. Such code review is practiced by virtually all software projects
that involve more than one person. Code review should be viewed as an
opportunity for you to learn how to write code that fits into the ASE codebase.
|