|
4 | 4 | </a> |
5 | 5 | </p> |
6 | 6 |
|
7 | | -<h3 align="center">The JavaScript implementation of the IPFS protocol.</h3> |
8 | | - |
9 | | -<p align="center"> |
10 | | - <a href="http://protocol.ai"><img src="https://img.shields.io/badge/made%20by-Protocol%20Labs-blue.svg?style=flat" /></a> |
11 | | - <a href="http://ipfs.io/"><img src="https://img.shields.io/badge/project-IPFS-blue.svg?style=flat" /></a> |
12 | | -</p> |
| 7 | +<h3 align="center">The JavaScript implementation of the IPFS protocol</h3> |
13 | 8 |
|
14 | 9 | <p align="center"> |
15 | 10 | <a href="https://riot.im/app/#/room/#ipfs-dev:matrix.org"><img src="https://img.shields.io/badge/matrix-%23ipfs%3Amatrix.org-blue.svg?style=flat" /> </a> |
|
27 | 22 |
|
28 | 23 | > **Upgrading from <=0.40 to 0.41?** See the [release notes](https://github.com/ipfs/js-ipfs/issues/2656) for the list of API changes and the [migration guide](https://gist.github.com/alanshaw/04b2ddc35a6fff25c040c011ac6acf26). |
29 | 24 |
|
30 | | -### Project status - `Alpha` <!-- omit in toc --> |
31 | | - |
32 | | -We've come a long way, but this project is still in Alpha, lots of development is happening, API might change, beware of the Dragons 🐉. |
| 25 | +We've come a long way, but this project is still in Alpha, lots of development is happening, APIs might change, beware of 🐉.. |
33 | 26 |
|
34 | | -**Want to get started?** Check our [examples folder](/examples) to learn how to spawn an IPFS node in Node.js and in the Browser. |
| 27 | +## Getting started |
35 | 28 |
|
36 | | -🚨 **Please read this** 🚨 The [DHT](https://en.wikipedia.org/wiki/Distributed_hash_table), a fundamental piece for automatic content and peer discovery is not yet complete. There are multiple applications that can be built without this service but nevertheless it is fundamental to getting that magic IPFS experience. The current status is that implementation is done and merged and we're working on performance issues. Expect the DHT to be available in a release very soon. |
37 | | - |
38 | | -[**`Weekly Core Implementations Call`**](https://github.com/ipfs/team-mgmt/issues/992) |
| 29 | +* Look into the [examples folder](https://github.com/ipfs/js-ipfs/tree/master/examples) to learn how to spawn an IPFS node in Node.js and in the Browser |
| 30 | +* Read the [Core API docs](https://github.com/ipfs/js-ipfs/tree/master/docs/core-api) to see what you can do with an IPFS node |
| 31 | +* Visit https://dweb-primer.ipfs.io to learn about IPFS and the concepts that underpin it |
| 32 | +* Head over to https://proto.school to take interactive tutorials that cover core IPFS APIs |
| 33 | +* Check out https://docs-beta.ipfs.io for tips, how-tos and more |
39 | 34 |
|
40 | 35 | ## Tech Lead <!-- omit in toc --> |
41 | 36 |
|
42 | 37 | [David Dias](https://github.com/daviddias) |
43 | 38 |
|
44 | 39 | ## Lead Maintainer <!-- omit in toc --> |
45 | 40 |
|
46 | | -[Alan Shaw](https://github.com/alanshaw) |
| 41 | +[Alex Potsides](http://github.com/achingbrain) |
47 | 42 |
|
48 | 43 | ## Table of Contents <!-- omit in toc --> |
49 | 44 |
|
| 45 | +- [Getting started](#getting-started) |
| 46 | +- [Documentation](#documentation) |
50 | 47 | - [Structure](#structure) |
51 | | -- [Development](#development) |
52 | | - - [Clone and install dependencies](#clone-and-install-dependencies) |
53 | | - - [Run tests](#run-tests) |
54 | | - - [Lint](#lint) |
55 | | - - [Build a dist version](#build-a-dist-version) |
56 | | - - [Publishing new versions](#publishing-new-versions) |
57 | | - - [Using prerelease versions](#using-prerelease-versions) |
58 | | -- [Contribute](#contribute) |
59 | | - - [Want to hack on IPFS?](#want-to-hack-on-ipfs) |
| 48 | +- [Want to hack on IPFS?](#want-to-hack-on-ipfs) |
60 | 49 | - [License](#license) |
61 | 50 |
|
| 51 | +## Documentation |
| 52 | + |
| 53 | +* [Core API](./docs/core-api) |
| 54 | +* [Examples](./examples) |
| 55 | +* [Development](./docs/DEVELOPMENT.md) |
| 56 | + |
62 | 57 | ## Structure |
63 | 58 |
|
64 | 59 | This project is broken into several modules, their purposes are: |
65 | 60 |
|
66 | 61 | * [`/packages/ipfs`](./packages/ipfs) The core implementation |
67 | 62 | * [`/packages/ipfs-http-client`](./packages/ipfs-http-client) A client for the RPC-over-HTTP API presented by both js-ipfs and go-ipfs |
68 | 63 | * [`/packages/interface-ipfs-core`](./packages/interface-ipfs-core) Tests to ensure adherance of an implementation to the spec |
69 | | -* [`/packages/ipfs-utils`](./packages/ipfs-utils) Helpers and utilities common to core and the HTTP RPC API client |
70 | | -* [`/packages/ipfs-mfs`](./packages/ipfs-mfs) The mfs implementation |
71 | | -* [`/packages/ipfs-multipart`](./packages/ipfs-multipart) A module that handles adding files via multipart HTTP requests for core and the mfs |
72 | | - |
73 | | -## Development |
74 | | - |
75 | | -### Clone and install dependencies |
76 | | - |
77 | | -```sh |
78 | | -> git clone https://github.com/ipfs/js-ipfs.git |
79 | | -> cd js-ipfs |
80 | | -> npm install |
81 | | -``` |
82 | | - |
83 | | -This will install [lerna](https://www.npmjs.com/package/lerna) and bootstrap the various packages, deduping and hoisting dependencies into the root folder. |
84 | | - |
85 | | -If later you add new dependencies to submodules or just wish to remove all the `node_modules`/`dist` folders and start again, run `npm run reset && npm install` from the root. |
86 | | - |
87 | | -See the scripts section of the root [`package.json`](./package.json) for more commands. |
88 | | - |
89 | | -### Run tests |
90 | | - |
91 | | -```sh |
92 | | -# run all the unit tests |
93 | | -> npm test |
94 | | - |
95 | | -# run just IPFS tests in Node.js |
96 | | -> npm run test:node |
| 64 | +* [`/packages/ipfs-core-utils`](./packages/ipfs-core-utils) Helpers and utilities common to core and the HTTP RPC API client |
97 | 65 |
|
98 | | -# run just IPFS tests in a browser |
99 | | -> npm run test:browser |
| 66 | +## Want to hack on IPFS? |
100 | 67 |
|
101 | | -# run just IPFS tests in a webworker |
102 | | -> npm run test:webworker |
103 | | -``` |
104 | | - |
105 | | -More granular test suites can be run from each submodule. |
106 | | - |
107 | | -Please see the `package.json` in each submodule for available commands. |
108 | | - |
109 | | -### Lint |
110 | | - |
111 | | -Please run the linter before submitting a PR, the build will not pass if it fails: |
112 | | - |
113 | | -```sh |
114 | | -> npm run lint |
115 | | -``` |
116 | | - |
117 | | -### Build a dist version |
118 | | - |
119 | | -```sh |
120 | | -> npm run build |
121 | | -``` |
122 | | - |
123 | | -### Publishing new versions |
124 | | - |
125 | | -1. Ensure you have a `GH_TOKEN` env var containing a GitHub [Personal Access Token](https://github.com/settings/tokens) with `public_repo` permissions |
126 | | -2. From the root of this repo run `npm run release` and follow the on screen prompts. It will use [conventional commits](https://www.conventionalcommits.org) to work out the new package version |
127 | | - |
128 | | -### Using prerelease versions |
129 | | - |
130 | | -Any changed packages from each successful build of master are published to npm as canary builds under the npm tag `next`. |
| 68 | +[](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) |
131 | 69 |
|
132 | | -## Contribute |
| 70 | +The IPFS implementation in JavaScript needs your help! There are a few things you can do right now to help out: |
133 | 71 |
|
134 | | -IPFS implementation in JavaScript is a work in progress. As such, there's a few things you can do right now to help out: |
| 72 | +Read the [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md) and [JavaScript Contributing Guidelines](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md). |
135 | 73 |
|
136 | | -- Go through the modules below and **check out existing issues**. This would be especially useful for modules in active development. Some knowledge of IPFS may be required, as well as the infrastructure behind it - for instance, you may need to read up on p2p and more complex operations like muxing to be able to help technically. |
137 | | -- **Perform code reviews**. More eyes will help (a) speed the project along, (b) ensure quality, and (c) reduce possible future bugs. |
138 | | -- Take a look at go-ipfs and some of the planning repositories or issues: for instance, the [libp2p spec](https://github.com/ipfs/specs/pull/19). Contributions here that would be most helpful are **top-level comments** about how it should look based on our understanding. Again, the more eyes the better. |
| 74 | +- **Check out existing issues** The [issue list](https://github.com/ipfs/js-ipfs/issues) has many that are marked as ['help wanted'](https://github.com/ipfs/js-ipfs/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22) or ['difficulty:easy'](https://github.com/ipfs/js-ipfs/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Adifficulty%3Aeasy) which make great starting points for development, many of which can be tackled with no prior IPFS knowledge |
| 75 | +- **Look at the [IPFS Roadmap](https://github.com/ipfs/roadmap)** This are the high priority items being worked on right now |
| 76 | +- **Perform code reviews** More eyes will help |
| 77 | + a. speed the project along |
| 78 | + b. ensure quality, and |
| 79 | + c. reduce possible future bugs. |
139 | 80 | - **Add tests**. There can never be enough tests. |
| 81 | +- **Join the [Weekly Core Implementations Call](https://github.com/ipfs/team-mgmt/issues/992)** it's where everyone discusses what's going on with IPFS and what's next |
140 | 82 |
|
141 | | -### Want to hack on IPFS? |
142 | | - |
143 | | -[](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) |
144 | | - |
145 | | -Check out [ipfs/community/CONTRIBUTING_JS.md](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md) for details on coding standards, commit messages and other project conventions |
146 | 83 |
|
147 | 84 | ## License |
148 | 85 |
|
|
0 commit comments