..
This file is part of INSPIRE.
Copyright (C) 2017 CERN.
INSPIRE is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
INSPIRE is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with INSPIRE. If not, see .
In applying this licence, CERN does not waive the privileges and immunities
granted to it by virtue of its status as an Intergovernmental Organization
or submit itself to any jurisdiction.
Basic development flow
**********************
Git configuration
=================
First of all we have to set up some basic git configuration values:
* Set up the user info that will be used by Git as author and committer for
each commit.
.. code-block:: console
git config --global user.name "name surname"
git config --global user.email "your@email.here"
* Configure git to add the `Signed-off-by` header on each commit:
.. code-block:: console
git config --global format.signoff true
Recommended: configure your ssh key on GitHub
============================================
That will allow you to easily access the git repositories without having to
enter your user and password every time in a secure manner.
If you don't have one already, create an ssh key:
.. code-block:: console
ssh-keygen
It will ask for a path and a password, the password is optional.
Now go to the `github settings page for keys`_ and add the contents of the
public key you just created, by default `~/.ssh/id_rsa.pub`.
.. warning::
Never share you private key with anybody! (by default ~/.ssh/id_rsa)
Recomended: install the hub tool for git-github integration
===========================================================
There's a tool created by github that adds some extra commands and better
integration with github to the git command, you can download it from `the hub
tool git repo`_.
Throughout this guide you will see also some tips that use it.
Clone the code
==============
Navigate to your work directory (or wherever you want to put the code) and
clone the main repository from github:
.. code-block:: console
cd ~/Work # or wherever you want to store the repo
git clone git@github.com:inspirehep/inspire-next
cd inspire-next
You will need also to add your personal fork, to do so just:
.. code-block:: console
git remote add git@github.com:/inspire-next
Replacing `` with your github username.
Now to make sure you have the correct remotes set up, you can run:
.. code-block:: console
git remote -v
And that should show two, one called `origin` that points to the inspirehep
repo, and one called `` that points to your fork.
If for any reason you messed up or want to change the url or add/remove a
remote, check the commands:
.. code-block:: console
git remote add
git remote remove
git remote set-url
.. note::
If you are using the hub tool, you can clone the inspire repo, fork it and
setup the remotes with:
.. code-block:: console
hub clone inspirehep/inspire-next
cd inspire-next
hub fork
Create your feature branch
==========================
Before starting to make changes, you should create a branch for them:
.. code-block:: console
git checkout -b add_feature_x
It's a good habit to name your feature branch in a way that hints about what it
is adding/fixing/removing, for example, instead of `my_changes` it's way better
to have `adds_user_auth_to_workflows`.
Do your changes
===============
Now you can start modifying, addin or removing files, try to create commits
regularily, and avoid mixing up changes on the same commit. For example, commit
any linting changes to existing code in a different commit to the addition of
code, or the addition of the tests.
To commit the changes:
.. code-block:: console
git add
git rm
git add
git commit
About the commit message structure, we try to follow the `Invenio commit
guideline`_, but we put a strong emphasis in the content, specially:
* Describe why you did the change, not what the change is (the diff already
shows the what).
* In the message body, add as many information as you need, it's better to be
extra verbose than the alternative.
* If it adresses an issue, add the coment `closes #1234` to the description,
where `#1234` is the issue number on github.
Create a pull request
=====================
As soon as you have worked some time doing changes, it's recommended to share
them, even if they are not ready yet, so in case that there's a misundestanding
on how to do the change, you don't find out after spending a lot of time on it.
To create the pull request, first you have to push your changes to your
repositoy:
.. code-block:: console
git push -f
.. note::
The `-f` flag is required if it's not the first time you push, and you
rebased your changes in between.
Now you can go to your github repo page, and create a new pull request, that
will ask you to specify a new message and description for it, if you had
multiple commits, try to summarize them there, that will help with the review.
.. note::
If you are using the hub tool, you can create a pull request with:
.. code-block:: console
hub pull-request
.. warning::
At this point, travis will test your changes and give you some feedback on
github. To avoid ping-ponging with travis and save you some time, it's
highly recommended to run the tests locally first, that will also allow you
to debug any issues.
By default, your pull request will start with the flag `WIP`, while this is
set, you can push to it as many times as you want. Once your changes are ready
to be reviewed, add the `Need: Review` flag and remove the `WIP`. It's also
recommended to request a review directly to someone if you know that she's good
in the domain of the pull request.
Update your changes
=====================
Some pull requests might take some time to merge, and other changes get merged
before to master. That might generate some code conflicts or make your tests
fail (or force you to change some of your code).
To resolve that issue, you should rebase on the latest master branch
periodically (try to do it at the very least once a day).
To do so:
* Fetch changes from the remotes:
.. code-block:: console
git fetch --all
* Rebase your code and edit, drop, squash, cherry-pick and/or reword commits.
This step will force you to resolve any conflicts that might arise.
.. code-block:: console
git rebase -i origin/master
* Run the tests again to make sure nothing got broken.
Documentation
=============
Same as tests, documentation is part of the development process, so whenever
you write code, you should keep this priorities in mind:
* Very readable code is best.
* Good comments is good.
* Extra documentation is ok.
Documentation will be required though for some parts of the code meant to be
reused several times, like apis, utility functions, etc.
The format of the docstrings that we use is the Google style one defined in the
`Napoleon Sphinx extension page`_.
More details
============
Some useful links are listed bellow:
`Official git documentation
`_
`Git branching tutorial
`_
`General git tutorial
`_
.. _github settings page for keys: https://github.com/settings/keys
.. _the hub tool git repo: https://github.com/github/hub
.. _Invenio commit guideline: http://invenio.readthedocs.io/en/latest/technology/git.html#r2-remarks-on-commit-log-messages
.. _Napoleon Sphinx extension page: http://www.sphinx-doc.org/en/stable/ext/napoleon.html