diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1fe151b07..0377d4d29 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,9 +1,81 @@ # Contributing -It is recommended to run unit tests and static code analysis before committing changes. +You want to contribute to `golem-js`? That's great! This guide will help you get started. + +## Setup local environment + +1. Clone this repository +2. In the root of this project run `npm install` to install all necessary dependencies +3. To build the SDK run `npm run build` +4. Install yagna as described in the [README](./README.md) file - you will need it to test your changes against testnet (no real funds will be required to execute workloads on Golem Network) + +### Unit Testing + +For unit testing `golem-js` uses `jest` with [ts-mockito](https://www.npmjs.com/package/@johanblumenberg/ts-mockito) to mock code. + +You can run tests using: ```bash -yarn lint -# and -yarn format +npm run test:unit +``` + +The test files are usually co-located with the files that they test in the `src/` folder. + +### Pre-commit hooks + +We use `husky` to enforce few rules using `prettier`, `eslint` or even commit message format which allows us to use [semantic-release](https://github.com/semantic-release/semantic-release). + +## Pull Request Guidelines + +Our development revolves around few branches: + +- `master` - contains the latest stable production code (production track) +- `beta` - where the SDK team developers next major releases (slow track) +- `alpha` - when a different major release has to take precedence before `beta` (fast track) + +The process is as follows: + +- Depending on the contribution you're planning to make, create a `feature/`, `bugfix/` branch from the base branch (typically `master`), and merge back against that branch. +- In case of any contribution: + - Make sure you provide proper description for the PR (see template below) + - Add test cases if possible within the same PR + +### PR description templates + +#### Feature + +```markdown +## Why is it needed? + +_Explain why the feature is valuable and what problem does it solve._ + +## What should be changed? + +_Explain the general idea behind the code changes - high level description of your solution to the problem stated above._ +``` + +#### Bugfix + +```markdown +## Steps to reproduce + +1. _Do this_ +2. _Then that_ +3. _Finally this_ + +## Expected result + +_Describe the desired outcome (how does fixed look like)_ + +## Actual result + +_Describe the actual outcome (what happens now)_ ``` + +## Discord + +Feel invited to join our [Discord](http://discord.gg/golem). You can meet other SDK users and developers in the `#sdk-discussion` and `#js-discussion` channels. + +## Thanks 💙 + +Thanks for all your contributions and efforts towards improving `golem-js`! diff --git a/README.md b/README.md index 8e0831414..5dd25331e 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,9 @@ +
+ +

+ golem-js SDK logo +

+ # Golem JavaScript API ![GitHub](https://img.shields.io/github/license/golemfactory/golem-js) @@ -23,12 +29,12 @@ - [Getting started with Golem Network](#getting-started-with-golem-network) - [Obtain an `app-key` to use with SDK](#obtain-an-app-key-to-use-with-sdk) - [Usage](#usage) - - [Read more](#read-more) - [Examples](#examples) - [Documentation](#documentation) - [Debugging](#debugging) - [Testing](#testing) - - [Reporting issues](#reporting-issues) + - [Contributing](#contributing) + - [Discord](#discord) - [See also](#see-also) @@ -37,7 +43,7 @@ Become a **Requestor** in the **Golem Network** and use this SDK to: - 🌐 Acquire compute resources from Providers using a convenient API -- 🚢 Deploy run your workloads with these resources and get the results back to your machine +- 🚢 Run your workloads with these resources and get the results back to your machine - 🔐 Build N-tier application deployments and run them within a VPN - 💰 Settle payments with Providers for the resources you've utilized @@ -159,7 +165,7 @@ const order: MarketOrderSpec = { try { await glm.connect(); // Rent a machine - const rental = await glm.oneOf(order); + const rental = await glm.oneOf({ order }); await rental .getExeUnit() .then((exe) => exe.run("echo Hello, Golem! 👋")) @@ -173,11 +179,7 @@ const order: MarketOrderSpec = { })().catch(console.error); ``` -### Read more - -- Read about [other available usage patterns](./docs/USAGE.md) to learn more on how you can leverage the SDK. -- Check the [`examples` directory](./examples) for working examples showcasing various features of the SDK. All examples - are continuously E2E tested. +Read about [other available usage patterns](./docs/USAGE.md) to learn more on how you can leverage the SDK. ## Examples @@ -202,13 +204,17 @@ the [debug package documentation](https://www.npmjs.com/package/debug). ## Testing -Read the dedicated [testing documentation](./TESTING.md) to learn more about how to run tests of the SDK. +Read the dedicated [testing documentation](./docs/TESTING.md) to learn more about how to run tests of the SDK. -## Reporting issues +## Contributing -In case you find an issue with the examples or the SDK itself, feel free to submit +Read the [Contributing Guide](./CONTRIBUTING.md) for details on how you can get involved. In case you find an issue with the examples or the SDK itself, feel free to submit an [issue report](https://github.com/golemfactory/golem-js/issues) to the repository. +## Discord + +Feel invited to join our [Discord](http://discord.gg/golem). You can meet other SDK users and developers in the `#sdk-discussion` and `#js-discussion` channels. + ## See also - [Golem](https://golem.network), a global, open-source, decentralized supercomputer that anyone can access. diff --git a/docs/CONCEPTS.md b/docs/CONCEPTS.md index 7c8640947..19fc46620 100644 --- a/docs/CONCEPTS.md +++ b/docs/CONCEPTS.md @@ -17,7 +17,7 @@ This document explains the concepts modelled by the SDK which foster your intera - [Why is it needed](#why-is-it-needed) - [What it should do](#what-it-should-do-1) - [How it was done](#how-it-was-done-1) - + ## Resource Rental Model @@ -70,7 +70,7 @@ If you're familiar with containers, you can picture the architecture in the foll > > The above comparison is used only for illustrative purposes. Golem GVMIs, ExeUnits and Activities behave differently compared to Docker or Kubernetes. -As a Requestor you're interested in quickly executing your commands within the container that runs youre image. The `ExeUnit` abstraction delivered by the SDK is meant to do enable you to do so. +As a Requestor you're interested in quickly executing your commands within the container that runs your image. The `ExeUnit` abstraction delivered by the SDK is meant to do enable you to do so. ### What it should do diff --git a/TESTING.md b/docs/TESTING.md similarity index 100% rename from TESTING.md rename to docs/TESTING.md diff --git a/docs/USAGE.md b/docs/USAGE.md index d46a87d68..31b141fcf 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -38,7 +38,7 @@ const order: MarketOrderSpec = { try { await glm.connect(); // Rent a machine - const rental = await glm.oneOf(order); + const rental = await glm.oneOf({ order }); await rental .getExeUnit() .then((exe) => exe.run("echo Hello, Golem! 👋")) diff --git a/src/golem-network/golem-network.ts b/src/golem-network/golem-network.ts index 7e1cd1331..72e4b546a 100644 --- a/src/golem-network/golem-network.ts +++ b/src/golem-network/golem-network.ts @@ -357,7 +357,7 @@ export class GolemNetwork { * * @example * ```ts - * const rental = await glm.oneOf(demand); + * const rental = await glm.oneOf({ order }); * await rental * .getExeUnit() * .then((exe) => exe.run("echo Hello, Golem! 👋"))