mirror of
https://github.com/bigchaindb/bigchaindb.git
synced 2024-10-13 13:34:05 +00:00
Problem: Docs re contributing needed editing & reorg
Solution: Edit & reorg them
This commit is contained in:
Troy McConaghy
@@ -0,0 +1,9 @@
|
||||
Developer Setup, Coding & Contribution Process
|
||||
==============================================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
setup-dev-environment
|
||||
write-code
|
||||
vanshdeep-notes
|
||||
@@ -0,0 +1,80 @@
|
||||
# Setup development environment
|
||||
|
||||
## Setting up a single node development environment with ``docker-compose``
|
||||
|
||||
You can also use [Docker Compose](https://docs.docker.com/compose/) to run all the tests.
|
||||
|
||||
```bash
|
||||
$ docker-compose build bigchaindb
|
||||
$ docker-compose up -d bdb
|
||||
```
|
||||
|
||||
The above command will launch all 3 main required services/processes:
|
||||
|
||||
* ``mongodb``
|
||||
* ``tendermint``
|
||||
* ``bigchaindb``
|
||||
|
||||
To follow the logs of the ``tendermint`` service:
|
||||
|
||||
```bash
|
||||
$ docker-compose logs -f tendermint
|
||||
```
|
||||
|
||||
To follow the logs of the ``bigchaindb`` service:
|
||||
|
||||
```bash
|
||||
$ docker-compose logs -f bigchaindb
|
||||
```
|
||||
|
||||
To follow the logs of the ``mongodb`` service:
|
||||
|
||||
```bash
|
||||
$ docker-compose logs -f mdb
|
||||
```
|
||||
|
||||
Simple health check:
|
||||
|
||||
```bash
|
||||
$ docker-compose up curl-client
|
||||
```
|
||||
|
||||
Post and retrieve a transaction -- copy/paste a driver basic example of a
|
||||
``CREATE`` transaction:
|
||||
|
||||
```bash
|
||||
$ docker-compose -f docker-compose.yml run --rm bdb-driver ipython
|
||||
```
|
||||
|
||||
**TODO**: A python script to post and retrieve a transaction(s).
|
||||
|
||||
### Running Tests
|
||||
|
||||
Run all the tests using:
|
||||
|
||||
```bash
|
||||
$ docker-compose run --rm --no-deps bigchaindb pytest -v
|
||||
```
|
||||
|
||||
Run tests from a file:
|
||||
|
||||
```bash
|
||||
$ docker-compose run --rm --no-deps bigchaindb pytest /path/to/file -v
|
||||
```
|
||||
|
||||
Run specific tests:
|
||||
```bash
|
||||
$ docker-compose run --rm --no-deps bigchaindb pytest /path/to/file -k "<test_name>" -v
|
||||
```
|
||||
|
||||
### Building Docs
|
||||
|
||||
You can also develop and build the BigchainDB docs using ``docker-compose``:
|
||||
|
||||
```bash
|
||||
$ docker-compose build bdocs
|
||||
$ docker-compose up -d bdocs
|
||||
```
|
||||
|
||||
The docs will be hosted on port **33333**, and can be accessed over [localhost](http:/localhost:33333), [127.0.0.1](http:/127.0.0.1:33333)
|
||||
OR http:/HOST_IP:33333.
|
||||
@@ -0,0 +1,163 @@
|
||||
# Vanshdeep's Notes on Running a Local Dev Node
|
||||
|
||||
The following doc describes how to run a local node for developing BigchainDB Tendermint version.
|
||||
|
||||
There are two crucial dependencies required to start a local node:
|
||||
|
||||
- MongoDB
|
||||
- Tendermint
|
||||
|
||||
and of course you also need to install BigchainDB Sever from the local code you just developed.
|
||||
|
||||
|
||||
## Installing MongoDB
|
||||
|
||||
MongoDB can be easily installed, just refer their [installation documentation](https://docs.mongodb.com/manual/installation/) for your distro.
|
||||
We know MongoDB 3.4 works with BigchainDB.
|
||||
MongoDB 3.6 _might_ work, or it might not. You could try it.
|
||||
After the installation of MongoDB is complete, run MongoDB using `sudo mongod --replSet=bigchain-rs`
|
||||
|
||||
|
||||
## Installing Tendermint
|
||||
|
||||
### Installing Tendermint Using Docker
|
||||
|
||||
Tendermint can be run directly using the docker image. Refer [here](https://hub.docker.com/r/tendermint/tendermint/) for more details.
|
||||
|
||||
|
||||
### Installing Tendermint from Source
|
||||
- Before we can begin installing Tendermint one should ensure that the Golang is installed on system and `$GOPATH` should be set in the `.bashrc` or `.zshrc`. An example setup is shown below
|
||||
|
||||
```bash
|
||||
|
||||
$ echo $GOPATH
|
||||
/home/user/Documents/go
|
||||
$ go -h
|
||||
Go is a tool for managing Go source code.
|
||||
|
||||
Usage:
|
||||
|
||||
go command [arguments]
|
||||
|
||||
The commands are:
|
||||
|
||||
build compile packages and dependencies
|
||||
clean remove object files
|
||||
|
||||
...
|
||||
|
||||
```
|
||||
|
||||
- We can drop `GOPATH` in `PATH` so that installed Golang packages are directly available in the shell. To do that add the following to your `.bashrc`
|
||||
|
||||
```bash
|
||||
export PATH=${PATH}:${GOPATH}/bin
|
||||
```
|
||||
|
||||
- Now we can install Glide which is vendor package manger for Golang,
|
||||
|
||||
```bash
|
||||
$ go get github.com/Masterminds/glide
|
||||
|
||||
...
|
||||
...
|
||||
|
||||
$ glide -h
|
||||
NAME:
|
||||
glide - Vendor Package Management for your Go projects.
|
||||
|
||||
Each project should have a 'glide.yaml' file in the project directory. Files
|
||||
look something like this:
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
- Now we install Tendermint from source,
|
||||
|
||||
```bash
|
||||
$ mkdir -p $GOPATH/src/github.com/tendermint && cd $_
|
||||
$ git clone https://github.com/tendermint/tendermint
|
||||
...
|
||||
$ cd tendermint && glide install
|
||||
$ go install ./cmd/tendermint
|
||||
```
|
||||
|
||||
- If the above commands were executed successfully then Tendermint is installed at `$GOPATH/bin`. To ensure Tendermint's installed fine execute the following command,
|
||||
|
||||
```bash
|
||||
$ tendermint -h
|
||||
Tendermint Core (BFT Consensus) in Go
|
||||
|
||||
Usage:
|
||||
tendermint [command]
|
||||
|
||||
Available Commands:
|
||||
gen_validator Generate new validator keypair
|
||||
help Help about any command
|
||||
init Initialize Tendermint
|
||||
...
|
||||
|
||||
```
|
||||
|
||||
### Running Tendermint
|
||||
- We can initialize and run tendermint as follows,
|
||||
```bash
|
||||
$ tendermint init
|
||||
...
|
||||
|
||||
$ tendermint node --consensus.create_empty_blocks=false
|
||||
```
|
||||
The argument `--consensus.create_empty_blocks=false` specifies that Tendermint should not commit empty blocks.
|
||||
|
||||
|
||||
- To reset all the data stored in Tendermint execute the following command,
|
||||
|
||||
```bash
|
||||
$ tendermint unsafe_reset_all
|
||||
```
|
||||
|
||||
## Installing BigchainDB
|
||||
|
||||
To install BigchainDB from source (for dev), clone the repo and execute the following command, (it is better that you create a virtual env for this)
|
||||
|
||||
```bash
|
||||
$ git clone https://github.com/bigchaindb/bigchaindb.git
|
||||
...
|
||||
$ git checkout tendermint
|
||||
$ pip install -e .[dev] # or pip install -e '.[dev]' # for zsh
|
||||
```
|
||||
|
||||
|
||||
## Running All Tests
|
||||
|
||||
To execute tests when developing a feature or fixing a bug one could use the following command,
|
||||
|
||||
```bash
|
||||
$ pytest -v --database-backend=localmongodb
|
||||
```
|
||||
|
||||
NOTE: MongoDB and Tendermint should be running as discussed above.
|
||||
|
||||
One could mark a specific test and execute the same by appending `-m my_mark` to the above command.
|
||||
|
||||
Although the above should prove sufficient in most cases but in case tests are failing on Travis CI then the following command can be used to possibly replicate the failure locally,
|
||||
|
||||
```bash
|
||||
$ docker-compose run --rm --no-deps bdb pytest -v --cov=bigchaindb
|
||||
```
|
||||
|
||||
NOTE: before executing the above command the user must ensure that they reset the Tendermint container by executing `tendermint usafe_reset_all` command in the Tendermint container.
|
||||
|
||||
|
||||
### Closing Notes
|
||||
|
||||
How to check `bigchaindb upsert-validator`:
|
||||
|
||||
- Clean bigchaindb (`bigchaindb drop`, `bigchaindb init`) and execute `bigchaindb upsert-validator B0E42D2589A455EAD339A035D6CE1C8C3E25863F268120AA0162AD7D003A4014 10`
|
||||
- Start Tendermint
|
||||
- `tendermint init`
|
||||
- `tendermint unsafe_reset_all`
|
||||
- `tendermint node --consensus.create_empty_blocks=false`
|
||||
- Start BigchainDB with `bichaindb start`
|
||||
- Execute `curl http://localhost:46657/validators`
|
||||
|
||||
@@ -0,0 +1,159 @@
|
||||
Write Code
|
||||
==========
|
||||
|
||||
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?
|
||||
|
||||
You should know why you want to write code before you go any farther.
|
||||
|
||||
|
||||
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.
|
||||
--------------------------------------
|
||||
|
||||
- Make sure you have Git installed.
|
||||
|
||||
- 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.).
|
||||
|
||||
- If you plan to do Python coding, get `the latest Python <https://www.python.org/downloads/>`_, and
|
||||
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/>`_.
|
||||
|
||||
- Use the latest ``pip`` to get the latest ``virtualenv``:
|
||||
|
||||
.. code::
|
||||
|
||||
$ pip install virtualenv
|
||||
|
||||
- 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
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Start Writing Code
|
||||
------------------
|
||||
|
||||
Use the Git `Fork and Pull Request Workflow <https://github.com/susam/gitpr>`_. Tip: You could print that page for reference.
|
||||
|
||||
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::
|
||||
|
||||
$ pip install pre-commit # might not do anything if it is already installed, which is okay
|
||||
$ pre-commit install
|
||||
|
||||
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.
|
||||
|
||||
To install BigchainDB Server from the local code, and to keep it up to date with the latest code in there, use:
|
||||
|
||||
.. code::
|
||||
|
||||
$ pip install -e .[dev]
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Remember to Write Tests
|
||||
-----------------------
|
||||
|
||||
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.
|
||||
|
||||
Most tests are in the ``tests/`` folder. Take a look around.
|
||||
|
||||
|
||||
Running a Local Node for Dev and Test
|
||||
-------------------------------------
|
||||
|
||||
This is tricky and personal. Different people do it different ways. We documented some of those on separate pages.
|
||||
|
||||
- `Vanshdeep's notes on dev node setup and running all tests locally <vanshdeep-notes.html>`_
|
||||
- More to come? (Potentially: using Docker Compose, Kubernetes and Minikube, or Ansible.)
|
||||
|
||||
|
||||
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.
|
||||
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``.
|
||||
|
||||
|
||||
First-Time Pull Requests from External Users
|
||||
--------------------------------------------
|
||||
|
||||
First-time pull requests from external users who haven't contributed before will get blocked by the requirement to agree to the
|
||||
BigchainDB Contributor License Agreement (CLA). It doesn't take long to agree to it. Go to
|
||||
`https://www.bigchaindb.com/cla/ <https://www.bigchaindb.com/cla/>`_ and:
|
||||
|
||||
- Select the CLA you want to agree to (for individuals or for a whole company)
|
||||
- Fill in the form and submit it
|
||||
- Wait for an email from us with the next step. There is only one: copying a special block of text to GitHub.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
-----------------
|
||||
|
||||
You are awesome. Do you want a job? `Apply! <https://github.com/bigchaindb/org/tree/master/jobs>`_ Berlin is great. If you got this far, we'd be happy to consider you joining our team. Look at these `Unsplash photos of Berlin <https://unsplash.com/search/photos/berlin>`_. So nice.
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user