Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Use prettier to format .md files #860

Merged
merged 2 commits into from
Mar 27, 2019
Merged

Use prettier to format .md files #860

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
04e7504
Use prettier to format .md files
Mar 27, 2019
54937cb
Reduce headline length in ROADMAP.md
Mar 27, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
636 changes: 347 additions & 289 deletions CHANGELOG.md
View file
Open in desktop

Large diffs are not rendered by default.

143 changes: 83 additions & 60 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,28 +2,35 @@

[![Build Status](https://travis-ci.com/iov-one/iov-core.svg?token=evC2AgcwxuvHjXeBP3jq&branch=master)](https://travis-ci.com/iov-one/iov-core)

This repo is provides core functionality to all clients in a cross-platform typescript library.
This can be used to build cli/gui clients, automated scripts, or help build bcp-proxy apps.
This repo is provides core functionality to all clients in a cross-platform
typescript library. This can be used to build cli/gui clients, automated
scripts, or help build bcp-proxy apps.

Main functionality provided:

- Solid crypto library with HD support for ed25519 (following SLIP-0010, ledger compatible)
- Secure private key management, including encrypted local storage for both browser and node
- Generic, type-safe adaptor to read/write on tendermint rpc server (with http/s and ws/s support)
- Solid crypto library with HD support for ed25519 (following SLIP-0010, ledger
compatible)
- Secure private key management, including encrypted local storage for both
browser and node
- Generic, type-safe adaptor to read/write on tendermint rpc server (with http/s
and ws/s support)
- Adaptor to query / create transactions for IOV's testnet of the BNS blockchain
- Adaptor for key management using IOV's BNS ledger app
- High level controller for managing multiple user profiles and various key material
- High level controller for managing read/write connections to multiple blockchains (CoreWriter)
- High level controller for managing multiple user profiles and various key
material
- High level controller for managing read/write connections to multiple
blockchains (CoreWriter)
- Integration with REPL environment for quick prototyping for developers

This is still in pre-alpha state and will evolve quickly as we add support for multiple blockchains,
more transactions types, and better extensibility. However, all attempts have been made that the
foundational code is quite solid. A security audit and stable release will occur along with the
timeline of IOV's mainnet launch, but developers looking for client-side libraries can do initial
This is still in pre-alpha state and will evolve quickly as we add support for
multiple blockchains, more transactions types, and better extensibility.
However, all attempts have been made that the foundational code is quite solid.
A security audit and stable release will occur along with the timeline of IOV's
mainnet launch, but developers looking for client-side libraries can do initial
prototypes with the current state.

We are actively building out multiple clients on top of this library and shaking out usability
issues in the API.
We are actively building out multiple clients on top of this library and shaking
out usability issues in the API.

## Users

Expand All @@ -37,12 +44,13 @@ The following projects use IOV-Core (add yourself via a PR):

## Compatibility

The compiled code from this package, which is published on npm, should work on any modern (2018)
browser, and node 8+. The development environment has been tested on node 8.7.0 LTS and node 10.x.
The compiled code from this package, which is published on npm, should work on
any modern (2018) browser, and node 8+. The development environment has been
tested on node 8.7.0 LTS and node 10.x.

**Yarn not Npm** Please `npm install -g yarn` and use `yarn install`, `yarn build`, etc.
Developers who installed with `npm i` have reported problems in compiling, so wipe out `node_modules`
and enjoy `yarn`.
**Yarn not Npm** Please `npm install -g yarn` and use `yarn install`,
`yarn build`, etc. Developers who installed with `npm i` have reported problems
in compiling, so wipe out `node_modules` and enjoy `yarn`.

CI Tests:

Expand All @@ -54,19 +62,22 @@ CI Tests:

## Getting Started

The best way to learn about code is to use it.
You can read some [examples in @iov/core](./packages/iov-core/README.md).
And you can use a REPL to [interactively try the code](./packages/iov-cli/README.md).
The best way to learn about code is to use it. You can read some
[examples in @iov/core](./packages/iov-core/README.md). And you can use a REPL
to [interactively try the code](./packages/iov-cli/README.md).

Once you understand the basics, you can dig in deeper with the API documentation.
Once you understand the basics, you can dig in deeper with the API
documentation.

## API Docs

Documentation is published at [https://iov-one.github.io/iov-core-docs/](https://iov-one.github.io/iov-core-docs/).
Documentation is published at
[https://iov-one.github.io/iov-core-docs/](https://iov-one.github.io/iov-core-docs/).

To build the documentation locally, run `yarn install && yarn build && yarn docs`
in this repository. This will generate a `./docs` directory in each package that you
can browse locally to see API docs on the various packages.
To build the documentation locally, run
`yarn install && yarn build && yarn docs` in this repository. This will generate
a `./docs` directory in each package that you can browse locally to see API docs
on the various packages.

## Contributing

Expand All @@ -79,9 +90,10 @@ that provide a nice way to get started with the IOV-Core repo.

### Development Environment

If you go into a subpackage and try to `yarn build` or `yarn test`, chances are it will fail.
The reason is that we only check in `*.ts` files, while we need the compiled `*.js` files
to import other packages. We push these to npm but do not check them into git to avoid commit noise.
If you go into a subpackage and try to `yarn build` or `yarn test`, chances are
it will fail. The reason is that we only check in `*.ts` files, while we need
the compiled `*.js` files to import other packages. We push these to npm but do
not check them into git to avoid commit noise.

To get started, please go to the root directory and run:

Expand All @@ -91,14 +103,14 @@ yarn build
yarn test
```

Once that passes, you have the code built and can go into any subdirectory, edit code
and verify the changes with `yarn test` on that one package.
Once that passes, you have the code built and can go into any subdirectory, edit
code and verify the changes with `yarn test` on that one package.

### Integration Tests

There are a number of integration tests involving communication with tendermint
(in `@iov/tendermint-rpc`) and the BNS blockchain (in `@iov/bns`) that require
a test server to run and are skipped by default. If you are working on those
(in `@iov/tendermint-rpc`) and the BNS blockchain (in `@iov/bns`) that require a
test server to run and are skipped by default. If you are working on those
packages, please run those tests. (They require docker to be installed and
executable by the current user)

Expand All @@ -118,8 +130,10 @@ unset TENDERMINT_ENABLED

#### BNS

If you are working on `@iov/bns`, you can run the tests against a local
BNS devnet. See [scripts/bnsd/README.md](https://github.com/iov-one/iov-core/tree/master/scripts/bnsd/README.md#start) for instructions on how to start the BNS devnet. Then run the tests as follows:
If you are working on `@iov/bns`, you can run the tests against a local BNS
devnet. See
[scripts/bnsd/README.md](https://github.com/iov-one/iov-core/tree/master/scripts/bnsd/README.md#start)
for instructions on how to start the BNS devnet. Then run the tests as follows:

```
cd packages/iov-bns
Expand All @@ -128,8 +142,10 @@ yarn test

#### Lisk

If you are working on `@iov/lisk`, you can run the tests against a local
Lisk devnet. See [scripts/lisk/README.md](https://github.com/iov-one/iov-core/tree/master/scripts/lisk#start) for instructions on how to start the Lisk devnet. Then run the tests as follows:
If you are working on `@iov/lisk`, you can run the tests against a local Lisk
devnet. See
[scripts/lisk/README.md](https://github.com/iov-one/iov-core/tree/master/scripts/lisk#start)
for instructions on how to start the Lisk devnet. Then run the tests as follows:

```
cd packages/iov-lisk
Expand All @@ -140,9 +156,9 @@ yarn test

The CI runs all code not only under node, but also in various browsers.

These work almost all of the time, but if you CI test fails in the browser,
or if you are just curious to see this work, you can run the browser tests
locally with any of the following, in any package you are working on:
These work almost all of the time, but if you CI test fails in the browser, or
if you are just curious to see this work, you can run the browser tests locally
with any of the following, in any package you are working on:

```
yarn test-chrome
Expand All @@ -153,19 +169,22 @@ yarn test-edge # windows only

### Developing under Windows 10

Most of the developers working on this project in windows are also using Windows Subsystem for Linux
(WSL), which should have maximum compatibility, as CI is linux and osx. However, we do attempt to ensure
that this code also compiles on the normal windows shell, if you have set up git, node, yarn etc. correctly.
(Note this has only be verified under windows 10, no guarantees for older versions).
Most of the developers working on this project in windows are also using Windows
Subsystem for Linux (WSL), which should have maximum compatibility, as CI is
linux and osx. However, we do attempt to ensure that this code also compiles on
the normal windows shell, if you have set up git, node, yarn etc. correctly.
(Note this has only be verified under windows 10, no guarantees for older
versions).

### Line endings (CRLF vs LF)

All the code in the repo should use LF not the windows-specific CRLF as a line ending.
`tsc` is currently set up to output properly. However, you should also make sure your editor
saves with `LF` line endings rather than `CRLF`.
All the code in the repo should use LF not the windows-specific CRLF as a line
ending. `tsc` is currently set up to output properly. However, you should also
make sure your editor saves with `LF` line endings rather than `CRLF`.

A bigger issue is `git` changing the endings upon commit. Here is a short workaround,
adapted from a [stackoverflow discussion](https://stackoverflow.com/questions/2517190/how-do-i-force-git-to-use-lf-instead-of-crlf-under-windows):
A bigger issue is `git` changing the endings upon commit. Here is a short
workaround, adapted from a
[stackoverflow discussion](https://stackoverflow.com/questions/2517190/how-do-i-force-git-to-use-lf-instead-of-crlf-under-windows):

```
git config --global core.autocrlf false
Expand All @@ -176,16 +195,18 @@ git config --global core.eol lf

### Libusb fails to build, why?

If you are running on linux, you may not have the proper dependencies installed. For Ubuntu, try the
following: `sudo apt-get install libudev-dev libusb-1.0-0 libusb-1.0-0-dev`.
These are needed to compile the usb driver.
If you are running on linux, you may not have the proper dependencies installed.
For Ubuntu, try the following:
`sudo apt-get install libudev-dev libusb-1.0-0 libusb-1.0-0-dev`. These are
needed to compile the usb driver.

Sometimes compiling native code with `node-pre-gyp` causes issues in very
recent versions of Node.js. At the moment, Node.js 8, 10 and 11 should work.
Sometimes compiling native code with `node-pre-gyp` causes issues in very recent
versions of Node.js. At the moment, Node.js 8, 10 and 11 should work.

### Docker fails to run a test server

If you're using OSX and Docker Desktop for Mac and you get an error like the following, you'll need to add your `$TMPDIR` path to the list of shared paths:
If you're using OSX and Docker Desktop for Mac and you get an error like the
following, you'll need to add your `$TMPDIR` path to the list of shared paths:

```
docker: Error response from daemon: Mounts denied:
Expand All @@ -200,14 +221,16 @@ In a terminal, run this command to find out your `$TMPDIR`:
echo $TMPDIR
```

Then add it to the list of shared paths in Docker -> Preferences ... -> File Sharing. Apply and restart, and try to start the test server again.
Then add it to the list of shared paths in Docker -> Preferences ... -> File
Sharing. Apply and restart, and try to start the test server again.

### My PR works but the CI rejects it

Make sure you at least ran `yarn test` in all the directories where you modified code.
The CI will reject any PR if type definitions change after compiling the code to ensure
it was build and committed prior to pushing.
Make sure you at least ran `yarn test` in all the directories where you modified
code. The CI will reject any PR if type definitions change after compiling the
code to ensure it was build and committed prior to pushing.

## License

This repository is licensed under the Apache License 2.0 (see NOTICE and LICENSE).
This repository is licensed under the Apache License 2.0 (see NOTICE and
LICENSE).
Loading