mirror of
https://github.com/bigchaindb/bigchaindb.git
synced 2024-10-13 13:34:05 +00:00
[WIP] Documentation re-org (#2694)
* Reorganized docs * Fixed internal links in basic usage * fixed the docker-compose command and volume for docs * fixed docs tests * fix travis docs test * tox ini file * fixed readme localhost links * edited tox and test docs to previous state * Fix tests errors related to docs reorganization Signed-off-by: David Dashyan <mail@davie.li> * Added ansible script installation option Signed-off-by: Lana Ivina <lana@ipdb.io> * Added ansible script to network setup guide Signed-off-by: Lana Ivina <lana@ipdb.io> * Hid the non-working button for now. Signed-off: Lana Ivina <lana@ipdb.io> * Try now button Co-authored-by: David Dashyan <mail@davie.li>
This commit is contained in:
lana-shanghai
@@ -0,0 +1,157 @@
|
||||
|
||||
.. Copyright © 2020 Interplanetary Database Association e.V.,
|
||||
BigchainDB and IPDB software contributors.
|
||||
SPDX-License-Identifier: (Apache-2.0 AND CC-BY-4.0)
|
||||
Code is Apache-2.0 and docs are CC-BY-4.0
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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/Network for Dev and Test
|
||||
---------------------------------------------
|
||||
|
||||
This is tricky and personal. Different people do it different ways. We documented some of those on separate pages:
|
||||
|
||||
- `Dev node setup and running all tests with Docker Compose <run-node-with-docker-compose.html>`_
|
||||
- `Dev node setup and running all tests as processes <run-node-as-processes.html>`_
|
||||
- `Dev network setup with stack.sh <run-dev-network-stack.html>`_
|
||||
- `Dev network setup with Ansible <run-dev-network-ansible.html>`_
|
||||
- More to come?
|
||||
|
||||
|
||||
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``.
|
||||
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user