From 594be8b8f172e641735305ae2429b0d5181cd558 Mon Sep 17 00:00:00 2001 From: Eric Harris-Braun Date: Tue, 8 Jan 2019 10:55:09 -0500 Subject: [PATCH 01/11] bump version to 0.0.3 --- app_spec/zomes/blog/code/Cargo.toml | 2 +- app_spec/zomes/summer/code/Cargo.toml | 2 +- cas_implementations/Cargo.toml | 2 +- cmd/Cargo.toml | 2 +- cmd/src/cli/scaffold/rust/lib.rs | 2 +- container/Cargo.toml | 2 +- container_api/Cargo.toml | 2 +- container_api/test-bridge-caller/Cargo.toml | 2 +- container_api/wasm-test/Cargo.toml | 2 +- core/Cargo.toml | 2 +- core/src/nucleus/actions/wasm-test/Cargo.toml | 2 +- core_api_c_binding/Cargo.toml | 2 +- core_types/Cargo.toml | 2 +- core_types_derive/Cargo.toml | 2 +- dna_c_binding/Cargo.toml | 2 +- hdk-rust/Cargo.toml | 2 +- hdk-rust/wasm-test/Cargo.toml | 2 +- net/Cargo.toml | 2 +- test_bin/Cargo.toml | 2 +- test_utils/Cargo.toml | 2 +- wasm_utils/Cargo.toml | 2 +- wasm_utils/wasm-test/integration-test/Cargo.toml | 2 +- 22 files changed, 22 insertions(+), 22 deletions(-) diff --git a/app_spec/zomes/blog/code/Cargo.toml b/app_spec/zomes/blog/code/Cargo.toml index a173247c00..97a83d7a9f 100644 --- a/app_spec/zomes/blog/code/Cargo.toml +++ b/app_spec/zomes/blog/code/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "code" -version = "0.0.2" +version = "0.0.3" authors = ["Holochain Core Dev Team "] [dependencies] diff --git a/app_spec/zomes/summer/code/Cargo.toml b/app_spec/zomes/summer/code/Cargo.toml index 0881ee5cc9..32a4f7202f 100644 --- a/app_spec/zomes/summer/code/Cargo.toml +++ b/app_spec/zomes/summer/code/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "code" -version = "0.0.2" +version = "0.0.3" authors = ["Holochain Core Dev Team "] [dependencies] diff --git a/cas_implementations/Cargo.toml b/cas_implementations/Cargo.toml index 81cfddf6f9..fdb16d9e77 100644 --- a/cas_implementations/Cargo.toml +++ b/cas_implementations/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "holochain_cas_implementations" -version = "0.0.2" +version = "0.0.3" authors = ["Holochain Core Dev Team "] [dependencies] diff --git a/cmd/Cargo.toml b/cmd/Cargo.toml index c59d603bee..be7b51cb8f 100644 --- a/cmd/Cargo.toml +++ b/cmd/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "hc" -version = "0.0.2" +version = "0.0.3" authors = ["Holochain Core Dev Team "] [dependencies] diff --git a/cmd/src/cli/scaffold/rust/lib.rs b/cmd/src/cli/scaffold/rust/lib.rs index eef15dbb10..2bf6a1e034 100644 --- a/cmd/src/cli/scaffold/rust/lib.rs +++ b/cmd/src/cli/scaffold/rust/lib.rs @@ -4,7 +4,7 @@ extern crate serde; extern crate serde_derive; extern crate serde_json; -// see https://developer.holochain.org/api/0.0.2/hdk/ for info on using the hdk library +// see https://developer.holochain.org/api/0.0.3/hdk/ for info on using the hdk library define_zome! { entries: [] diff --git a/container/Cargo.toml b/container/Cargo.toml index bc5607d24b..4c5efd8c63 100644 --- a/container/Cargo.toml +++ b/container/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "holochain_container" -version = "0.0.2" +version = "0.0.3" authors = ["Holochain Core Dev Team "] [dependencies] diff --git a/container_api/Cargo.toml b/container_api/Cargo.toml index ec0dcc338b..2e3865439c 100644 --- a/container_api/Cargo.toml +++ b/container_api/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "holochain_container_api" -version = "0.0.2" +version = "0.0.3" authors = ["Holochain Core Dev Team "] [dependencies] diff --git a/container_api/test-bridge-caller/Cargo.toml b/container_api/test-bridge-caller/Cargo.toml index 996bc91656..230f671169 100644 --- a/container_api/test-bridge-caller/Cargo.toml +++ b/container_api/test-bridge-caller/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "test-bridge-caller" -version = "0.0.2" +version = "0.0.3" authors = ["Holochain Core Dev Team "] [lib] diff --git a/container_api/wasm-test/Cargo.toml b/container_api/wasm-test/Cargo.toml index 4c2cbec0b5..cb0cd154fb 100644 --- a/container_api/wasm-test/Cargo.toml +++ b/container_api/wasm-test/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "example_api_wasm" -version = "0.0.2" +version = "0.0.3" authors = ["Holochain Core Dev Team "] [lib] diff --git a/core/Cargo.toml b/core/Cargo.toml index cfe4c9f586..3d65849466 100644 --- a/core/Cargo.toml +++ b/core/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "holochain_core" -version = "0.0.2" +version = "0.0.3" authors = ["Holochain Core Dev Team "] edition = "2018" diff --git a/core/src/nucleus/actions/wasm-test/Cargo.toml b/core/src/nucleus/actions/wasm-test/Cargo.toml index b810dff676..43cec71fcc 100644 --- a/core/src/nucleus/actions/wasm-test/Cargo.toml +++ b/core/src/nucleus/actions/wasm-test/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "nucleus-actions-tests" -version = "0.0.2" +version = "0.0.3" authors = ["Holochain Core Dev Team "] [lib] diff --git a/core_api_c_binding/Cargo.toml b/core_api_c_binding/Cargo.toml index 6b8627167b..6b7235968a 100644 --- a/core_api_c_binding/Cargo.toml +++ b/core_api_c_binding/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "holochain_core_api_c_binding" -version = "0.0.2" +version = "0.0.3" authors = ["Holochain Core Dev Team "] [lib] diff --git a/core_types/Cargo.toml b/core_types/Cargo.toml index 5178732c4d..1ef14d9720 100644 --- a/core_types/Cargo.toml +++ b/core_types/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "holochain_core_types" -version = "0.0.2" +version = "0.0.3" authors = ["Holochain Core Dev Team "] [dependencies] diff --git a/core_types_derive/Cargo.toml b/core_types_derive/Cargo.toml index 7e90460ad0..f425630afa 100644 --- a/core_types_derive/Cargo.toml +++ b/core_types_derive/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "holochain_core_types_derive" -version = "0.0.2" +version = "0.0.3" authors = ["Holochain Core Dev Team "] [lib] diff --git a/dna_c_binding/Cargo.toml b/dna_c_binding/Cargo.toml index ff8fc4ecac..b26b072395 100644 --- a/dna_c_binding/Cargo.toml +++ b/dna_c_binding/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "holochain_dna_c_binding" -version = "0.0.2" +version = "0.0.3" authors = ["Holochain Core Dev Team "] [lib] diff --git a/hdk-rust/Cargo.toml b/hdk-rust/Cargo.toml index 9ad28549b7..44094b5807 100644 --- a/hdk-rust/Cargo.toml +++ b/hdk-rust/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "hdk" -version = "0.0.2" +version = "0.0.3" authors = ["Holochain Core Dev Team "] [dependencies] diff --git a/hdk-rust/wasm-test/Cargo.toml b/hdk-rust/wasm-test/Cargo.toml index 763e6a395c..c1265102a9 100644 --- a/hdk-rust/wasm-test/Cargo.toml +++ b/hdk-rust/wasm-test/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "test-globals" -version = "0.0.2" +version = "0.0.3" authors = ["Holochain Core Dev Team "] [lib] diff --git a/net/Cargo.toml b/net/Cargo.toml index 417ef9b53c..c75329e482 100644 --- a/net/Cargo.toml +++ b/net/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "holochain_net" -version = "0.0.2" +version = "0.0.3" authors = ["Holochain Core Dev Team "] [dependencies] diff --git a/test_bin/Cargo.toml b/test_bin/Cargo.toml index a7413dddfa..188bb5deba 100644 --- a/test_bin/Cargo.toml +++ b/test_bin/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "holochain_test_bin" -version = "0.0.2" +version = "0.0.3" authors = ["Holochain Core Dev Team "] [dependencies] diff --git a/test_utils/Cargo.toml b/test_utils/Cargo.toml index d5d8ff0514..7ca86eb5a4 100644 --- a/test_utils/Cargo.toml +++ b/test_utils/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "test_utils" -version = "0.0.2" +version = "0.0.3" authors = ["Holochain Core Dev Team "] [dependencies] diff --git a/wasm_utils/Cargo.toml b/wasm_utils/Cargo.toml index 8e53d6d813..1ff9a9764f 100644 --- a/wasm_utils/Cargo.toml +++ b/wasm_utils/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "holochain_wasm_utils" -version = "0.0.2" +version = "0.0.3" authors = ["Holochain Core Dev Team "] [dependencies] diff --git a/wasm_utils/wasm-test/integration-test/Cargo.toml b/wasm_utils/wasm-test/integration-test/Cargo.toml index 099d8552c6..78bcc4ba07 100644 --- a/wasm_utils/wasm-test/integration-test/Cargo.toml +++ b/wasm_utils/wasm-test/integration-test/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "wasm-integration-test" -version = "0.0.2" +version = "0.0.3" authors = ["Holochain Core Dev Team "] [lib] From fa2816f6844ab097894d00cef0fe51ab6003c257 Mon Sep 17 00:00:00 2001 From: Eric Harris-Braun Date: Tue, 8 Jan 2019 14:37:04 -0500 Subject: [PATCH 02/11] update readme and contributing --- CONTRIBUTING.md | 179 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 136 ++++++------------------------------ 2 files changed, 199 insertions(+), 116 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..51a25c1a4b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,179 @@ +# Contributing + +[![Project](https://img.shields.io/badge/project-holochain-blue.svg?style=flat-square)](http://holochain.org/) +[![Chat](https://img.shields.io/badge/chat-chat%2eholochain%2enet-blue.svg?style=flat-square)](https://chat.holochain.net) + +As an Open Source project Holochain welcomes many sorts of contributions, bug-report & fixes, code contributes, documentation, tests, feedback and more. + +## Social +We are committed to foster a vibrant thriving community, including growing a culture that breaks cycles of marginalization and dominance behavior. In support of this, some open source communities adopt [Codes of Conduct](http://contributor-covenant.org/version/1/3/0/). We are still working on our social protocols, and empower each team to describe its own *Protocols for Inclusion*. Until our teams have published their guidelines, please use the link above as a general guideline. + +## Coordination + +* For task management we use [Waffle](https://waffle.io/holochain/org) or for the non-kan-ban view [github's issues](https://github.com/holochain/org/issuees) +* Chat with us on our [chat server](https://chat.holochain.net) or [Gitter](https://gitter.im/metacurrency/holochain) + +## Test Driven Development +We use **test driven development**. When you add a new function or feature, be sure to add both unit tests and integration tests to shows that it works. Pull requests without tests will most-likely not be accepted! + +## App Spec Driven Development +In adding significant changes and new features to Holochain, we follow a specific test-driven development protocol: +1. Start by creating a branch in this repository and modifying the example app in the app_spec directory to demonstrates an actual implementation of the use of the new feature, including tests that would pass if the feature were actually implemented. +1. Create a pull request on that branch for the development team to talk about and discuss the suggested change. The PR triggers Continuous Integration tests which will initially fail. +1. Do any development necessary in core or hdk crates of this repo to actually implement the feature demonstrated in `app_spec` +1. Finally, when the feature is fully implemented, the CI tests should turn green and the branch can be merged. + +In this way `app_spec` works as a living specification with example app to build against. + +## Compiler warnings + +Compilation warnings are NOT OK in shared/production level code. + +Warnings have a nasty habit of piling up over time. This makes your code increasingly unpleasant for other people to work with. + +CI MUST fail or pass, there is no use in the ever noisier "maybe" status. + +If you are facing a warning locally you can try: + +0. Fixing it +1. Using `#[allow(***)]` inline to surgically override a once-off issue +2. Proposing a global `allow` for a specific rule + - this is an extreme action to take + - this should only be considered if it can be shown that: + - the issue is common (e.g. dozens of `#allow[***]`) + - disabling it won't cause issues/mess to pile up elsewhere + - the wider Rust community won't find our codebase harder to work with + +If you don't know the best approach, please ask for help! + +It is NOT OK to disable `deny` for warnings globally at the CI or makefile/nix level. + +You can allow warnings locally during development by setting the `RUSTFLAGS` environment variable. + +#### Code style +We use rust-fmt to enforce code style so that we don't spend time arguing about this. + +Run the formatter with: + +```shell +. docker/run-fmt +``` +or + +``` shell +make fmt +``` + +or + +``` shell +nix-shell --run hc-fmt +``` + +## Continuous Integration + +### CI configuration changes + +Please also be aware that extending/changing the CI configuration can be very time consuming. Seemingly minor changes can have large downstream impact. + +Some notable things to watch out for: + +- Adding changes that cause the Travis cache to be dropped on every run +- Changing the compiler/lint rules that are shared by many people +- Changing versions of crates/libs that also impact downstream crates/repos +- Changing the nightly version of Rust used +- Adding/removing tools or external libs + +The change may not be immediately apparent to you. The change may break the development environment on a different operating system, e.g. Windows. + +At the same time, we do not want to catastrophise and stifle innovation or legitimate upgrades. + +If you have a proposal to improve our CI config, that is great! + +Please open a dedicated branch for the change in isolation so we can discuss the proposal together. + +Please broadcast the proposal in chat to maximise visibility and the opportunity for everyone to respond. + +It is NOT OK to change the behaviour of tests/CI in otherwise unrelated PRs. SOMETIMES it MAY be OK to change CI in a related PR, e.g. adding a new lib that your code requires. DO expect that a change like this will probably attract additional scrutiny during the PR review process, which is unfortunate but important. + +Use your best judgement and respect that other people, across all timezones, rely on this repository remaining a productive working environment 24/7/365. + +### Updating the CI Environment + +The continuous integration (CI) suite executes the same `. docker/run-test` command that developers are encouraged to run. + +What happens if I need to change that environment? E.g. what if I need a new system library dependency installed? + +- Step 1 - Add the dependency to `docker/Dockerfile.ubuntu` + +```dockerfile +RUN apt-get update && apt-get install --yes\ + # ... snip ... + my-new-lib-here +``` + +- Step 2 - Build it + +```shell +. docker/build-ubuntu +``` + +- Step 3 - Test it out + +```shell +. docker/run-test +``` + +- Step 4 - Wait a minute! The CI environment is still using the old Dockerfile! + +If your changes do not break the current environment, you can submit a separate Pull Request first, and once it is merged, the CI environment should be up-to-date for your code change Pull Request. + +Otherwise, you will need to speak to an admin who can force merge your full changes after testing locally. + +The continuous integration (CI) suite executes the same `. docker/run-test` command that developers are encouraged to run. + +What happens if I need to change that environment? E.g. what if I need a new system library dependency installed? + +- Step 1 - Add the dependency to `docker/Dockerfile.ubuntu` + +```dockerfile +RUN apt-get update && apt-get install --yes\ + # ... snip ... + my-new-lib-here +``` + +- Step 2 - Build it + +```shell +. docker/build-ubuntu +``` + +- Step 3 - Test it out + +```shell +. docker/run-test +``` + +- Step 4 - Wait a minute! The CI environment is still using the old Dockerfile! + +If your changes do not break the current environment, you can submit a separate Pull Request first, and once it is merged, the CI environment should be up-to-date for your code change Pull Request. + +Otherwise, you will need to speak to an admin who can force merge your full changes after testing locally. + + +## Git Hygiene +This section describes our practices and guidelines for using git and making changes to the repo. + +* We use Github's pull requests as our code review tool +* We encourage any dev to comment on pull requests and we think of the pull request not as a "please approve my code" but as a space for co-developing, i.e. asynchronous "pair-coding" of a sort. +* We develop features on separate branches identified by the Github issue number, i.e. `124-my-new-feature` +* We use merge (not rebase) so that commits related to a ticket can be retroactively explored. +* In most repos development happens on a `develop` branch which gets merged to master when there's a release. + +## License +The default licensing for our repos is currently [![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](http://www.gnu.org/licenses/gpl-3.0) +Copyright (C) 2018, Holochain Trust + +**Note:** We are considering other 'looser' licensing options (like MIT license) but at this stage are using GPL while we're getting the matter sorted out. See [this article](https://medium.com/holochain/licensing-needs-for-truly-p2p-software-a3e0fa42be6c) for some of our thinking on licensing for distributed application frameworks. + +If you contribute code do so knowing that we may change the licensing from GPL to some other form like MIT without notification. diff --git a/README.md b/README.md index f387c62f29..5cfd7ce894 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,3 @@ - # Holochain-rust holochain logo @@ -28,14 +27,12 @@ This `holochain-rust` repository implements a number of distinct yet overlapping 1. A library for the core Holochain functionality for defining and running DNA instances: [*core*](#core) 1. A library and syntax for use in Rust based development of Zomes within DNAs, called Holochain Development Kit: [*hdk-rust*](#hdk-rust) -1. A library for managing instances and connecting them to interfaces: [*container_api*](#container-api) +1. A library for managing instances and connecting them to interfaces: [*container-api*](#container-api) 1. A Rust based container that uses the container_api: [*container*](#rust-container) -1. A nodejs based container for running tests: [*container*](#nodejs-container) +1. A nodejs based container for running tests: [*nodejs-container*](#nodejs-container) 1. A command line developer tool: [*hc*](#hc-command-line-developer-tool) 1. A sample application that we use to demonstrate the current functionality and drive development: [*app-spec*](#app-spec-driven-development) -Let's elaborate on these three aspects. - ### Core The [core](./core) folder contains the code that implements the core functionality of Holochain. It is the aspect that takes in an application DNA, and an agent, and securely runs peer-to-peer applications by exposing the API functions to Zomes. It draws on other top level definitions and functions such as [dna](./dna), [cas_implementations](./cas_implementations), [agent](./agent), and [core_types](./core_types). @@ -63,7 +60,7 @@ If you need to implement your own container, [container_api](container_api) shou To implement a container in a C based language, the [core_api_c_binding](./core_api_c_binding) [NEEDS UPDATING] code could be used, such as HoloSqape does. ### Rust Container -The [container crate](container) uses the [container_api](container_api) to implement an executable which is intended to become the main, highly configurable and GUI less container implementation that can be run as a background system service. Currently the Rust Container +The [container crate](container) uses the [container_api](container_api) to implement an executable which is intended to become the main, highly configurable and GUI less container implementation that can be run as a background system service. ### Nodejs Container The [nodejs_container](nodejs_container) directory implements a node package that creates a container that wraps the Holochain core Rust implementation so we can access it from node. This is crucial especially for creating a test-driven development environment for developing Holochain DNA. The `hc` command-line tool relies on it to run tests. @@ -71,6 +68,9 @@ The [nodejs_container](nodejs_container) directory implements a node package tha ### HC Command-line developer tool. The [cmd crate](cmd) implements our command line developer tool which allows you to create DNA scaffold, run tests, and finally package your DNA for running in a containter. For more details see the [crate README](cmd/README.md). +## App Spec Driven Development +We use a practice for coordinating additions and features that starts with adding a feature to a sample application so that we know we have a working example all the times. You can read about [the details here](/CONTRIBUTING.md#app-spec-driven-development) + ## Documentation: The Book on Holochain There is a work-in-progress book of documentation being written about `holochain-rust`. See the published version at the associated GitHub Pages for this repo, [https://developer.holochain.org/guide/latest](https://developer.holochain.org/guide/latest). See instructions for how to contribute to the book at [doc/holochain_101/src/how_to_contribute.md](./doc/holochain_101/src/how_to_contribute.md). @@ -82,10 +82,16 @@ There is a work-in-progress book of documentation being written about `holochain **The following instructions are for developing Holochain Core or the HDK itself** -There are two approaches to building and testing Holochain, using `make` or using `docker`: +There are three approaches to building and testing Holochain, using `make`, `docker` or `nix`: ### Make (ubuntu and macOS only) +For Ubuntu you can install the prerequisites with : + +``` shell +sudo apt-get install git build-essential libssl-dev curl +``` + If you are running on ubuntu or macOS, and you have `make` installed, you can do local development by simply typing: `make` which will: @@ -108,8 +114,6 @@ Not everything in the Makefile is implemented in nix, and a lot of things don't If you have a nix friendly system, this is probably the fastest way to develop and test. -e.g. `nix-shell --run hc-test` - #### Running tests Run: @@ -123,6 +127,12 @@ or make test ``` +or + +``` shell +nix-shell --run hc-test +``` + Note that there are also make commands for running the tests of just core, or the command-line line tools or app_spec separately: ``` shell @@ -132,118 +142,12 @@ make test_app_spec make build_nodejs_container ``` - -#### Code style -There is a linter/formatter enforcing code style. - -Run: - -```shell -. docker/run-fmt -``` -or - -``` shell -make fmt -``` - -#### Compiler warnings - -Compilation warnings are NOT OK in shared/production level code. - -Warnings have a nasty habit of piling up over time. This makes your code increasingly unpleasant for other people to work with. - -CI MUST fail or pass, there is no use in the ever noisier "maybe" status. - -If you are facing a warning locally you can try: - -0. Fixing it -1. Using `#[allow(***)]` inline to surgically override a once-off issue -2. Proposing a global `allow` for a specific rule - - this is an extreme action to take - - this should only be considered if it can be shown that: - - the issue is common (e.g. dozens of `#allow[***]`) - - disabling it won't cause issues/mess to pile up elsewhere - - the wider Rust community won't find our codebase harder to work with - -If you don't know the best approach, please ask for help! - -It is NOT OK to disable `deny` for warnings globally at the CI or makefile/nix level. - -You can allow warnings locally during development by setting the `RUSTFLAGS` environment variable. - -#### CI configuration changes - -Please also be aware that extending/changing the CI configuration can be very time consuming. Seemingly minor changes can have large downstream impact. - -Some notable things to watch out for: - -- Adding changes that cause the Travis cache to be dropped on every run -- Changing the compiler/lint rules that are shared by many people -- Changing versions of crates/libs that also impact downstream crates/repos -- Changing the nightly version of Rust used -- Adding/removing tools or external libs - -The change may not be immediately apparent to you. The change may break the development environment on a different operating system, e.g. Windows. - -At the same time, we do not want to catastrophise and stifle innovation or legitimate upgrades. - -If you have a proposal to improve our CI config, that is great! - -Please open a dedicated branch for the change in isolation so we can discuss the proposal together. - -Please broadcast the proposal in chat to maximise visibility and the opportunity for everyone to respond. - -It is NOT OK to change the behaviour of tests/CI in otherwise unrelated PRs. SOMETIMES it MAY be OK to change CI in a related PR, e.g. adding a new lib that your code requires. DO expect that a change like this will probably attract additional scrutiny during the PR review process, which is unfortunate but important. - -Use your best judgement and respect that other people, across all timezones, rely on this repository remaining a productive working environment 24/7/365. - -#### Updating the CI Environment - -The continuous integration (CI) suite executes the same `. docker/run-test` command that developers are encouraged to run. - -What happens if I need to change that environment? E.g. what if I need a new system library dependency installed? - -- Step 1 - Add the dependency to `docker/Dockerfile.ubuntu` - -```dockerfile -RUN apt-get update && apt-get install --yes\ - # ... snip ... - my-new-lib-here -``` - -- Step 2 - Build it - -```shell -. docker/build-ubuntu -``` - -- Step 3 - Test it out - -```shell -. docker/run-test -``` - -- Step 4 - Wait a minute! The CI environment is still using the old Dockerfile! - -If your changes do not break the current environment, you can submit a separate Pull Request first, and once it is merged, the CI environment should be up-to-date for your code change Pull Request. - -Otherwise, you will need to speak to an admin who can force merge your full changes after testing locally. - ### Building for Android Note there is an article written on how to build Holochain for Android, read it [here](doc/holochain_101/src/building_for_android.md). ## Contribute -Holochain is an open source project. We welcome all sorts of participation and are actively working on increasing surface area to accept it. Please see our [contributing guidelines](https://github.com/holochain/org/blob/master/CONTRIBUTING.md) for our general practices and protocols on participating in the community. - -### App Spec Driven Development -In adding significant changes and new features to Holochain, we follow a specific test-driven development protocol: -1. Start by creating a branch in this repository and modifying the example app in the app_spec directory to demonstrates an actual implementation of the use of the new feature, including tests that would pass if the feature were actually implemented. -1. Create a pull request on that branch for the development team to talk about and discuss the suggested change. The PR triggers Continuous Integration tests which will initially fail. -1. Do any development necessary in core or hdk crates of this repo to actually implement the feature demonstrated in `app_spec` -1. Finally, when the feature is fully implemented, the CI tests should turn green and the branch can be merged. +Holochain is an open source project. We welcome all sorts of participation and are actively working on increasing surface area to accept it. Please see our [contributing guidelines](/CONTRIBUTING.md) for our general practices and protocols on participating in the community, as well as specific expectations around things like code formatting, testing practices, continuous integration, etc. -In this way `app_spec` works as a living specification with example app to build against. Some helpful links: From 06ac77d32b61bc429e857cde13475975c409cd03 Mon Sep 17 00:00:00 2001 From: Eric Harris-Braun Date: Tue, 8 Jan 2019 15:48:54 -0500 Subject: [PATCH 03/11] fix makefile and reademe for install isntructions --- Makefile | 2 +- README.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index a98ce0ffc8..64f60fad5e 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ # run `make test_holochain` to test holochain builds # run `make test_cmd` to test the command line tool builds -all: lint build_holochain build_cmd +all: build_holochain build_cmd CORE_RUST_VERSION ?= nightly-2018-12-26 TOOLS_RUST_VERSION ?= nightly-2018-12-26 diff --git a/README.md b/README.md index 5cfd7ce894..20ed9e2899 100644 --- a/README.md +++ b/README.md @@ -76,13 +76,13 @@ There is a work-in-progress book of documentation being written about `holochain ## Installation & Usage -**Important:** for installation of the tools with which you can build Holochain applications, you will want to instead proceed to the instructions on the quick start installation guide. - -**https://developer.holochain.org/start.html** +**Important:** the instructions in this readme are for developers intending work on Holochain code-base itself, not Holochain application developers. If you want to use Holochain, please proceed to the instructions on the quick start installation guide: **https://developer.holochain.org/start.html** **The following instructions are for developing Holochain Core or the HDK itself** -There are three approaches to building and testing Holochain, using `make`, `docker` or `nix`: +There are two components needed currently to run Holochain applications, the core (what's in this repo) and also [the networking engine](https://github.com/holochain/n3h). You can install and work on core using the built-in mock network following the instructions below, but if you want to actually test out your apps using the real networking, you will have to install [the networking engine](https://github.com/holochain/n3h). + +There are three approaches to building and testing Holochain: using `make`, `docker` or `nix`: ### Make (ubuntu and macOS only) From 77c74f83b30db8fdd437f9ace443f085e3c98937 Mon Sep 17 00:00:00 2001 From: Eric Harris-Braun Date: Wed, 9 Jan 2019 12:57:06 -0500 Subject: [PATCH 04/11] update readme's re configuring real networking --- README.md | 2 +- container/README.md | 14 ++++++++++++-- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 20ed9e2899..23b3d3b120 100644 --- a/README.md +++ b/README.md @@ -80,7 +80,7 @@ There is a work-in-progress book of documentation being written about `holochain **The following instructions are for developing Holochain Core or the HDK itself** -There are two components needed currently to run Holochain applications, the core (what's in this repo) and also [the networking engine](https://github.com/holochain/n3h). You can install and work on core using the built-in mock network following the instructions below, but if you want to actually test out your apps using the real networking, you will have to install [the networking engine](https://github.com/holochain/n3h). +There are two components needed currently to run Holochain applications, the core (what's in this repo) and also [the networking engine](https://github.com/holochain/n3h). You can install and work on core using the built-in mock network following the instructions below, but if you want to actually test out your apps using the real networking, you will have to install [the networking component](https://github.com/holochain/n3h) following the instructions in the readme there. (Note: please see the instructions in the [`hc` command-line tool readme](./cmd/README.md#using-real-networking) or the [container readme](./container/README.md#using-real-networking) for how to configure the tools to use the find and activate the networking component. There are three approaches to building and testing Holochain: using `make`, `docker` or `nix`: diff --git a/container/README.md b/container/README.md index d85322c918..cf0d560e0a 100644 --- a/container/README.md +++ b/container/README.md @@ -41,16 +41,26 @@ The container requires a configuration file to run, you can see a [sample here]( You can put your configuration file in `~/.holochain/container_config.toml` or run `holochain_container` explicitly with the `-c` to specify where to find it. +### Using real networking +The container currently uses mock networking by default. To use real networking you have to install the [n3h networking component](https://github.com/holochain/n3h) and add a configuration block into the config file to tell the container where it can find n3h. It should look something like this: + +``` +[network] +n3h_path = "/home/eric/holochain/n3h" +n3h_persistence_path = "/tmp" +bootstrap_nodes = [] +``` + ## Configuration File Spec TBD (for now you just have infer from the example!) ## Limitations -Currently the container only supports the `websocket` interface. +Currently the container supports the `websocket` and `http` interfaces. ## Contribute -Holochain is an open source project. We welcome all sorts of participation and are actively working on increasing surface area to accept it. Please see our [contributing guidelines](https://github.com/holochain/org/blob/master/CONTRIBUTING.md) for our general practices and protocols on participating in the community. +Holochain is an open source project. We welcome all sorts of participation and are actively working on increasing surface area to accept it. Please see our [contributing guidelines](../CONTRIBUTING.md) for our general practices and protocols on participating in the community. ## License [![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](http://www.gnu.org/licenses/gpl-3.0) From 9b7075a3d538b77b98b716a45317a0b8db5ad645 Mon Sep 17 00:00:00 2001 From: Eric Harris-Braun Date: Wed, 9 Jan 2019 13:03:03 -0500 Subject: [PATCH 05/11] update various crate readmes --- app_spec/README.md | 2 +- hdk-rust/README.md | 2 +- nodejs_container/README.md | 15 +++++++++++++++ 3 files changed, 17 insertions(+), 2 deletions(-) diff --git a/app_spec/README.md b/app_spec/README.md index 3b5725add1..9a8b1cabb3 100644 --- a/app_spec/README.md +++ b/app_spec/README.md @@ -51,7 +51,7 @@ Unless they have already been installed, it will install node_modules to your `t Finally, it uses `hc` to run those tests, giving you the feedback you really want to test code, and develop new functionality. ## Contribute -Holochain is an open source project. We welcome all sorts of participation and are actively working on increasing surface area to accept it. Please see our [contributing guidelines](https://github.com/holochain/org/blob/master/CONTRIBUTING.md) for our general practices and protocols on participating in the community. +Holochain is an open source project. We welcome all sorts of participation and are actively working on increasing surface area to accept it. Please see our [contributing guidelines](../CONTRIBUTING.md) for our general practices and protocols on participating in the community. ## License [![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](http://www.gnu.org/licenses/gpl-3.0) diff --git a/hdk-rust/README.md b/hdk-rust/README.md index ab8c6c0f7c..ef78cafb00 100644 --- a/hdk-rust/README.md +++ b/hdk-rust/README.md @@ -20,7 +20,7 @@ As new features, or changes to the HDK (and the API) are being designed, use cas Please see the [Contribute section](https://github.com/holochain/holochain-rust/blob/develop/README.md#app-spec-driven-development) for our protocol on how we do this. ## Contribute -Holochain is an open source project. We welcome all sorts of participation and are actively working on increasing surface area to accept it. Please see our [contributing guidelines](https://github.com/holochain/org/blob/master/CONTRIBUTING.md) for our general practices and protocols on participating in the community. +Holochain is an open source project. We welcome all sorts of participation and are actively working on increasing surface area to accept it. Please see our [contributing guidelines](../CONTRIBUTING.md) for our general practices and protocols on participating in the community. ## License [![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](http://www.gnu.org/licenses/gpl-3.0) diff --git a/nodejs_container/README.md b/nodejs_container/README.md index 7fe33c1b23..1d0c785990 100644 --- a/nodejs_container/README.md +++ b/nodejs_container/README.md @@ -100,3 +100,18 @@ Until windows for travis can utilize secure environment variables without breaki ## Acknowledgments - Thanks to IronCoreLabs for the example of deploying neon modules via npm (https://github.com/IronCoreLabs/recrypt-node-binding) + +## Contribute +Holochain is an open source project. We welcome all sorts of participation and are actively working on increasing surface area to accept it. Please see our [contributing guidelines](../CONTRIBUTING.md) for our general practices and protocols on participating in the community. + +## License +[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](http://www.gnu.org/licenses/gpl-3.0) + +Copyright (C) 2018, Holochain Trust + +This program is free software: you can redistribute it and/or modify it under the terms of the license p +rovided in the LICENSE file (GPLv3). This program is distributed in the hope that it will be useful, bu +t WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR + PURPOSE. + +**Note:** We are considering other 'looser' licensing options (like MIT license) but at this stage are using GPL while we're getting the matter sorted out. See [this article](https://medium.com/holochain/licensing-needs-for-truly-p2p-software-a3e0fa42be6c) for some of our thinking on licensing for distributed application frameworks. From 06c1f72aa57425d380837327de4232311ae066cd Mon Sep 17 00:00:00 2001 From: Connor Turland Date: Wed, 9 Jan 2019 14:39:36 -0500 Subject: [PATCH 06/11] remove waffle and correct docs references --- README.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 23b3d3b120..27aa78ecc8 100644 --- a/README.md +++ b/README.md @@ -3,22 +3,22 @@ holochain logo [![Project](https://img.shields.io/badge/project-holochain-blue.svg?style=flat-square)](http://holochain.org/) -[![PM](https://img.shields.io/badge/pm-waffle-blue.svg?style=flat-square)](https://waffle.io/holochain/org) [![Chat](https://img.shields.io/badge/chat-chat%2eholochain%2enet-blue.svg?style=flat-square)](https://chat.holochain.net) [![Twitter Follow](https://img.shields.io/twitter/follow/holochain.svg?style=social&label=Follow)](https://twitter.com/holochain) [![Travis](https://img.shields.io/travis/holochain/holochain-rust/develop.svg)](https://travis-ci.org/holochain/holochain-rust/branches) [![Codecov](https://img.shields.io/codecov/c/github/holochain/holochain-rust.svg)](https://codecov.io/gh/holochain/holochain-rust/branch/develop) -[![In Progress](https://img.shields.io/waffle/label/holochain/holochain-rust/in%20progress.svg)](http://waffle.io/holochain/holochain-rust) [![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](http://www.gnu.org/licenses/gpl-3.0) This is the home of the Holochain Rust libraries, being rewritten from [Go](https://github.com/holochain/holochain-proto) into Rust, and extended. -**[Code Status:](https://github.com/holochain/holochain-rust/milestones?direction=asc&sort=completeness&state=all)** Rust version is currently Pre-Alpha. Not for production use. The code has not yet undergone a security audit. We expect to destructively restructure code APIs and data chains until Beta. Prototype go version was unveiled at our first hackathon (March 2017), with go version Alpha 0 released October 2017. Alpha 1 was released May 2018. We expect a developer pre-release of this Rust re-write in mid October 2018. +**Code Status:** Rust version is currently Pre-Alpha. Not for production use. The code has not yet undergone a security audit. We expect to destructively restructure code APIs and data chains until Beta. Prototype go version was unveiled at our first hackathon (March 2017), with go version Alpha 0 released October 2017. Alpha 1 was released May 2018. + +There are [3 developer preview releases](/releases) of the Rust version. 0.0.3 is the first with a working networking implementation.
-| Holochain Links: | [FAQ](https://holochain.github.io/holochain-rust/faq.html) | [Developer Docs](https://holochain.github.io/holochain-rust/) | [White Paper](https://github.com/holochain/holochain-proto/blob/whitepaper/holochain.pdf) | +| Holochain Links: | [FAQ](https://developer.holochain.org/guide/latest/faq.html) | [Developer Docs](https://developer.holochain.org) | [White Paper](https://github.com/holochain/holochain-proto/blob/whitepaper/holochain.pdf) | |---|---|---|---| ## Overview @@ -48,7 +48,7 @@ Any language that compiles to WASM and can serialize/deserialize JSON data can b An HDK for [Assemblyscript](https://github.com/Assemblyscript/assemblyscript) is under experimental development at [`hdk-assemblyscript`](https://github.com/holochain/hdk-assemblyscript). -We expect many more languages to be added by the community, and there is even an article on how to [write a kit for a new language](https://holochain.github.io/holochain-rust/writing_development_kit.html). +We expect many more languages to be added by the community, and there is even an article on how to [write a kit for a new language](https://developer.holochain.org/guide/latest/writing_development_kit.html). ### Container API *Core* only implements the logic for the execution of a single application. Because the Holochain app ecosystem relies on DNA composibility, we need to be able to load and instantiate multiple DNAs. We call an executable that can do this an *container*. The first such containers we implemented were the GUI driven [holosqape](https://github.com/holochain/holosqape) and the CLI driven [hcshell](https://github.com/holochain/holosqape#hcshell) container which we used for running javascript based tests. @@ -148,16 +148,10 @@ Note there is an article written on how to build Holochain for Android, read it ## Contribute Holochain is an open source project. We welcome all sorts of participation and are actively working on increasing surface area to accept it. Please see our [contributing guidelines](/CONTRIBUTING.md) for our general practices and protocols on participating in the community, as well as specific expectations around things like code formatting, testing practices, continuous integration, etc. - Some helpful links: -* View our [Kanban on Waffle](https://waffle.io/holochain/org) [![In Progress](https://img.shields.io/waffle/label/holochain/holochain-rust/in%20progress.svg)](http://waffle.io/holochain/holochain-rust) * Chat with us on our [Chat Server](https://chat.holochain.org) or [Gitter](https://gitter.im/metacurrency/holochain) -Current Throughput graph: - -[![Throughput Graph](http://graphs.waffle.io/holochain/holochain-rust/throughput.svg)](https://waffle.io/holochain/holochain-rust/metrics) - ## License [![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](http://www.gnu.org/licenses/gpl-3.0) From 1ab6b444735b816be8f7b623ffb8e2c86e97e486 Mon Sep 17 00:00:00 2001 From: Connor Turland Date: Wed, 9 Jan 2019 14:41:33 -0500 Subject: [PATCH 07/11] fix releases link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 27aa78ecc8..ad2808a701 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ This is the home of the Holochain Rust libraries, being rewritten from [Go](http **Code Status:** Rust version is currently Pre-Alpha. Not for production use. The code has not yet undergone a security audit. We expect to destructively restructure code APIs and data chains until Beta. Prototype go version was unveiled at our first hackathon (March 2017), with go version Alpha 0 released October 2017. Alpha 1 was released May 2018. -There are [3 developer preview releases](/releases) of the Rust version. 0.0.3 is the first with a working networking implementation. +There are [3 developer preview releases](https://github.com/holochain/holochain-rust/releases) of the Rust version. 0.0.3 is the first with a working networking implementation.
| Holochain Links: | [FAQ](https://developer.holochain.org/guide/latest/faq.html) | [Developer Docs](https://developer.holochain.org) | [White Paper](https://github.com/holochain/holochain-proto/blob/whitepaper/holochain.pdf) | From c68d22f6c95aec96f447229cdf3f7ee4556bdc52 Mon Sep 17 00:00:00 2001 From: Connor Turland Date: Wed, 9 Jan 2019 16:26:29 -0500 Subject: [PATCH 08/11] remove waffle reference --- CONTRIBUTING.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 51a25c1a4b..63722ba4bd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,6 @@ We are committed to foster a vibrant thriving community, including growing a cul ## Coordination -* For task management we use [Waffle](https://waffle.io/holochain/org) or for the non-kan-ban view [github's issues](https://github.com/holochain/org/issuees) * Chat with us on our [chat server](https://chat.holochain.net) or [Gitter](https://gitter.im/metacurrency/holochain) ## Test Driven Development From 5b1e056244f73163a519f06b1952d2a5e497d817 Mon Sep 17 00:00:00 2001 From: Connor Turland Date: Wed, 9 Jan 2019 16:40:22 -0500 Subject: [PATCH 09/11] Update README.md Co-Authored-By: zippy --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ad2808a701..ccf394e957 100644 --- a/README.md +++ b/README.md @@ -80,7 +80,7 @@ There is a work-in-progress book of documentation being written about `holochain **The following instructions are for developing Holochain Core or the HDK itself** -There are two components needed currently to run Holochain applications, the core (what's in this repo) and also [the networking engine](https://github.com/holochain/n3h). You can install and work on core using the built-in mock network following the instructions below, but if you want to actually test out your apps using the real networking, you will have to install [the networking component](https://github.com/holochain/n3h) following the instructions in the readme there. (Note: please see the instructions in the [`hc` command-line tool readme](./cmd/README.md#using-real-networking) or the [container readme](./container/README.md#using-real-networking) for how to configure the tools to use the find and activate the networking component. +There are two components needed currently to run Holochain applications, the core (what's in this repo) and also [the networking engine](https://github.com/holochain/n3h). You can install and work on core using the built-in mock network following the instructions below, but if you want to actually test out your apps using the real networking, you will have to install [the networking component](https://github.com/holochain/n3h) following the instructions in the readme there. (Note: please see the instructions in the [`hc` command-line tool readme](./cmd/README.md#using-real-networking) or the [container readme](./container/README.md#using-real-networking) for how to configure the tools to use and activate the networking component. There are three approaches to building and testing Holochain: using `make`, `docker` or `nix`: From 4a54892b32a5e837e2910252d243f24f9ab27ef9 Mon Sep 17 00:00:00 2001 From: Eric Harris-Braun Date: Wed, 9 Jan 2019 21:22:06 -0500 Subject: [PATCH 10/11] added change log --- CHANGELOG.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000000..6d1c877cf3 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,44 @@ +# Changelog +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] +### Changed +### Added +### Removed + +## [0.0.3] - 2019-01-09 +### Added +- Networking: beyond mock, using [n3h](https://github.com/holochain/n3h) +- Bridging now works and is configurable in the container (no capabilities yet) [#779](https://github.com/holochain/holochain-rust/pull/779) & [#776](https://github.com/holochain/holochain-rust/pull/776) +- Validation across network [#727](https://github.com/holochain/holochain-rust/pull/727) +- API/HDK: + - CRUD for entries working + - Node-to-node messaging [#746](https://github.com/holochain/holochain-rust/pull/746) + - GetEntryOptions: + - retrieve CRUD history & status + - meta data: sources + - GetLinksOptions + - meta data: sources + - GetLinks helpers: get_links_and_load + - Query: return multiple entry types with glob matching [#781](https://github.com/holochain/holochain-rust/pull/781) +- Container: + - configuration builder and config files + - http interface [#823](https://github.com/holochain/holochain-rust/pull/823) +- hc command-line tool: + - `run --persist` flag for keeping state across runs [#729](https://github.com/holochain/holochain-rust/pull/729/files) + - +- Groundwork for: capabilities & signals +- Improved debug logging with log rules and colorization [#819](https://github.com/holochain/holochain-rust/pull/819) +- This change log! + +### Changed +- API/HDK: + - native return types (JsonStrings) + - many places where we referred to "Hash" we now use the more correct term "Address" + +## [0.0.2] - 2018-11-28 +### Added +- mock networking +- `hc run` with support for +- multi-instance scenario testing From e4ed0790025ec76a8804c469f2b51d3f20d70da9 Mon Sep 17 00:00:00 2001 From: Eric Harris-Braun Date: Wed, 9 Jan 2019 21:43:46 -0500 Subject: [PATCH 11/11] fixes to change-log --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6d1c877cf3..ab90438c41 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,8 +27,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - http interface [#823](https://github.com/holochain/holochain-rust/pull/823) - hc command-line tool: - `run --persist` flag for keeping state across runs [#729](https://github.com/holochain/holochain-rust/pull/729/files) - - -- Groundwork for: capabilities & signals + - Added env variables to activate real networking [#826](https://github.com/holochain/holochain-rust/pull/826) +- Groundwork for: capabilities & signals [#762](https://github.com/holochain/holochain-rust/pull/826) & [#732](https://github.com/holochain/holochain-rust/pull/732) - Improved debug logging with log rules and colorization [#819](https://github.com/holochain/holochain-rust/pull/819) - This change log!