2018-08-16 12:31:32 +02:00
.. Copyright BigchainDB GmbH and BigchainDB contributors
SPDX-License-Identifier: (Apache-2.0 AND CC-BY-4.0)
Code is Apache-2.0 and docs are CC-BY-4.0
2018-03-06 23:55:18 +01:00
Write Code
==========
2018-03-27 10:18:51 +02:00
Know What You Want to Write Code to Do
--------------------------------------
Do you want to write code to resolve an open issue (bug)? Which one?
Do you want to implement a BigchainDB Enhancement Proposal (BEP)? Which one?
2018-03-06 23:55:18 +01:00
2018-03-27 10:18:51 +02:00
You should know why you want to write code before you go any farther.
2018-03-06 23:55:18 +01:00
Refresh Yourself about the C4 Process
-------------------------------------
C4 is the Collective Code Construction Contract. It's quite short:
`re-reading it will only take a few minutes <https://github.com/bigchaindb/BEPs/tree/master/1> `_ .
Set Up Your Local Machine. Here's How.
--------------------------------------
2018-03-12 14:23:49 +01:00
- Make sure you have Git installed.
2018-03-06 23:55:18 +01:00
- Get a text editor. Internally, we like:
- Vim
- PyCharm
- Visual Studio Code
- Atom
- GNU Emacs (Trent is crazy)
- GNU nano (Troy has lost his mind)
- If you plan to do JavaScript coding, get the latest JavaScript stuff (npm etc.).
2018-03-07 12:37:08 +01:00
- If you plan to do Python coding, get `the latest Python <https://www.python.org/downloads/> `_ , and
2018-03-06 23:55:18 +01:00
get the latest `` pip `` .
.. warning ::
Don't use apt or apt-get to get the latest `` pip `` . It won't work properly. Use `` get-pip.py ``
from `the pip website <https://pip.pypa.io/en/stable/installing/> `_ .
2018-03-12 14:23:49 +01:00
- Use the latest `` pip `` to get the latest `` virtualenv `` :
2018-03-06 23:55:18 +01:00
.. code ::
$ pip install virtualenv
2018-03-12 14:23:49 +01:00
- Create a Python Virttual Environment (virtualenv) for doing BigchainDB Server development. There are many ways to do that. Google around and pick one.
An old-fashioned but fine way is:
.. code ::
$ virtualenv -p $(which python3.6) NEW_ENV_NAME
$ . NEW_ENV_NAME/bin/activate
2018-03-06 23:55:18 +01:00
2018-03-12 14:23:49 +01:00
Be sure to use Python 3.6.x as the Python version for your virtualenv. The virtualenv creation process will actually get the
latest `` pip `` , `` wheel `` and `` setuptools `` and put them inside the new virtualenv.
2018-03-06 23:55:18 +01:00
2018-03-12 14:23:49 +01:00
2019-04-15 23:47:56 +02:00
Before You Start Writing Code
-----------------------------
Read `BEP-24 <https://github.com/bigchaindb/BEPs/tree/master/24> `_
so you know what to do to ensure that your changes (i.e. your future pull request) can be merged.
It's easy and will save you some hassle later on.
2018-03-12 14:23:49 +01:00
Start Writing Code
------------------
Use the Git `Fork and Pull Request Workflow <https://github.com/susam/gitpr> `_ . Tip: You could print that page for reference.
2018-03-06 23:55:18 +01:00
Your Python code should follow `our Python Style Guide <https://github.com/bigchaindb/bigchaindb/blob/master/PYTHON_STYLE_GUIDE.md> `_ .
Similarly for JavaScript.
Make sure `pre-commit <https://pre-commit.com/> `_ actually checks commits. Do:
.. code ::
2018-03-12 14:23:49 +01:00
$ pip install pre-commit # might not do anything if it is already installed, which is okay
2018-03-06 23:55:18 +01:00
$ pre-commit install
2018-03-12 14:23:49 +01:00
That will load the pre-commit settings in the file `` .pre-commit-config.yaml `` . Now every time you do `` git commit <stuff> `` , pre-commit
will run all those checks.
2018-03-06 23:55:18 +01:00
2018-03-12 14:23:49 +01:00
To install BigchainDB Server from the local code, and to keep it up to date with the latest code in there, use:
2018-03-06 23:55:18 +01:00
2018-03-12 14:23:49 +01:00
.. code ::
2018-03-06 23:55:18 +01:00
2018-03-12 14:23:49 +01:00
$ pip install -e .[dev]
2018-03-06 23:55:18 +01:00
2018-03-12 14:23:49 +01:00
The `` -e `` tells it to use the latest code. The `` . `` means use the current directory, which should be the one containing `` setup.py `` .
The `` [dev] `` tells it to install some extra Python packages. Which ones? Open `` setup.py `` and look for `` dev `` in the `` extras_require `` section.
2018-03-06 23:55:18 +01:00
2018-03-12 14:23:49 +01:00
Remember to Write Tests
-----------------------
2018-03-06 23:55:18 +01:00
2018-03-12 14:23:49 +01:00
We like to test everything, if possible. Unit tests and also integration tests. We use the `pytest <https://docs.pytest.org/en/latest/> `_
framework to write Python tests. Read all about it.
2018-03-06 23:55:18 +01:00
2018-03-12 14:23:49 +01:00
Most tests are in the `` tests/ `` folder. Take a look around.
2018-03-27 16:41:26 +02:00
2018-03-06 23:55:18 +01:00
2018-05-31 16:56:45 +02:00
Running a Local Node/Network for Dev and Test
---------------------------------------------
2018-03-12 14:23:49 +01:00
2018-03-27 12:02:33 +02:00
This is tricky and personal. Different people do it different ways. We documented some of those on separate pages:
2018-03-12 14:23:49 +01:00
2018-05-14 09:57:48 +02:00
- `Dev node setup and running all tests with Docker Compose <run-node-with-docker-compose.html> `_
2018-03-27 16:38:58 +02:00
- `Dev node setup and running all tests as processes <run-node-as-processes.html> `_
2018-05-31 16:56:45 +02:00
- `Dev network setup with stack.sh <run-dev-network-stack.html> `_
- `Dev network setup with Ansible <run-dev-network-ansible.html> `_
2018-03-27 12:02:33 +02:00
- More to come?
2018-03-06 23:55:18 +01:00
Create the PR on GitHub
-----------------------
Git push your branch to GitHub so as to create a pull request against the branch where the code you want to change *lives* .
Travis and Codecov will run and might complain. Look into the complaints and fix them before merging.
2018-03-14 13:06:52 +01:00
Travis gets its configuration and setup from the files:
- Some environment variables, if they are used. See https://docs.travis-ci.com/user/environment-variables/
- `` .travis.yml ``
- `` tox.ini `` - What is tox? See `tox.readthedocs.io <https://tox.readthedocs.io/en/latest/> `_
- `` .ci/ `` (as in Travis CI = Continuous Integration)
- `` travis-after-success.sh ``
- `` travis-before-install.sh ``
- `` travis-before-script.sh ``
- `` travis-install.sh ``
- `` travis_script.sh ``
Read about the `Travis CI build lifecycle <https://docs.travis-ci.com/user/customizing-the-build/> `_ to understand when those scripts run and what they do.
You can have even more scripts!
Codecov gets its configuration from the file `codeocov.yaml <https://github.com/codecov/support/wiki/Codecov-Yaml> `_ which is also documented at
`docs.codecov.io <https://docs.codecov.io/v4.3.6/docs/codecov-yaml> `_ . Codecov might also use `` setup.cfg `` .
2018-03-06 23:55:18 +01:00
Merge!
------
Ideally, we like your PR and merge it right away. We don't want to keep you waiting.
If we want to make changes, we'll do them in a follow-up PR.