CONTRIBUTING.md

How to Contribute

We're excited to accept your contributions to TinyChain! If you're not sure where to get started, consider starting a discussion or creating an issue.

If you already have some changes you'd like to submit, just send a pull request. You can find instructions for creating a pull request in GitHub Help.

New Developer Quickstart Guide

Developing TinyChain itself is a little different than developing services that run on TinyChain. For example, you won't be able to use the TinyChain client from pip because you'll be making changes to the client itself! The best way to get started is to clone the git repository:

git clone https://github.com/haydnv/tinychain

If you prefer, you can fork the repo instead. That way, you'll be able to save your commits to GitHub before you contribute them upstream.

To run the client unit tests, make sure Python knows where to find your local copy of the TinyChain client:

# optional: create a virtual environment
# note: python may be python3 on some systems
python -m venv myenv

# note: pip may be pip3 on some systems
pip install -e client/py

Then, try running the client tests to make sure you've got everything configured correctly:

python3 -m tests.tctest.client

There are some more tests in the tests/host directory--don't worry about those yet. They require starting multiple hosts programmatically, which is covered in the next section on "Rust Development".

By default the client tests will run on demo.tinychain.net but if you do much development on TinyChain you'll probably want to run your own host. You can do that using Docker:

# you can change the --git URL to your own if you need
docker build --build-arg "CRATE=--git=https://github.com/haydnv/tinychain.git" .

# the docker build command will output an image ID when it finishes
# use that to run the image you just build

# --address=0.0.0.0 tells the TinyChain process inside the Docker container to listen on any address
# you can also add other startup parameters like --http_port, --cache_size, --help, etc
docker run -p 127.0.0.1:8702:8702/tcp <image ID> /tinychain --data_dir=/tmp/data

Check that your Dockerized TinyChain host is up and running by visiting http://localhost:8702/state/scalar/value/string?key=%22Hello,%20World!%22 in your browser.

Now that you have your own host running, you can run your client tests against it:

# tell the test suite what host to contact
export TC_HOST=http://127.0.0.1:8702

# run the tests
python3 -m tests.tctest.client

Rust Development

If you need to make changes to the TinyChain host software itself, you'll need to run it locally. Follow the steps in the Manual install section of the documentation to set up Rust, then check that you've gotten everything set up correctly by running the host tests:

python3 -m tests.tctest.host

Licensing

By contributing code to the TinyChain project, you represent that you own the copyright on your contributions, or that you have followed the licensing requirements of the copyright holder, and that TinyChain may use your code without any further restrictions than those specified in the Apache 2.0 open-source license. A copy of the license can be found in the LICENSE file in the root directory of the project.

Code of Conduct

This project follows the Contributor Covenant code of conduct.