Skip to content
This repository has been archived by the owner on Aug 1, 2022. It is now read-only.

Expand DEVELOPMENT proxy section #192

Merged
merged 10 commits into from
Mar 4, 2020
Merged

Expand DEVELOPMENT proxy section #192

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
ef8a392
Expand DEVELOPMENT proxy section
xla Feb 26, 2020
880b158
Correct flag
xla Feb 26, 2020
dd87b6c
Apply suggestions from @rudolfs
xla Feb 26, 2020
7878cd7
Merge branch 'master' into xla/191-extend-proxy-development
xla Mar 4, 2020
95f7765
Apply suggestions from code review
xla Mar 4, 2020
536b402
Link downstream protocol projects
xla Mar 4, 2020
7b1c657
Improve language
xla Mar 4, 2020
9e60754
Correct position of test disclaimer
xla Mar 4, 2020
4b037b7
Add proxy commands with explanations
xla Mar 4, 2020
fba57ac
Address feedback
xla Mar 4, 2020
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
92 changes: 83 additions & 9 deletions DEVELOPMENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -378,7 +378,6 @@ be used so changes to global styling can be applied in a central place.
You can build and package Upstream with: `yarn dist`. The generated package
will be in: `dist/` as `radicle-upstream-X.X.X.{dmg|AppImage|snap}`.


## Scripts

To get a list of all available script commands, run: `yarn run`.
Expand All @@ -395,7 +394,7 @@ yarn dist # Bundles Upstream into an installable package
yarn generate:colors # Update color CSS variables in public/colors.css from
# colors.json

yern generate:schema # Start proxy and save the latest GraphQL schema
yarn generate:schema # Start proxy and save the latest GraphQL schema
# in ./schema.gql

yarn graphiql # Open GraphiQL with explorer extension in browser
Expand All @@ -411,9 +410,14 @@ yarn lint # Check UI code for linting errors

## Proxy

All Upstream business logic tying together the radicle code collaboration and
registry protocols is provided to the UI via GraphQL by a rust binary called
the proxy.
All of Upstream's business logic tying together the radicle code collaboration and
registry protocols is provided to the UI via [GraphQL][gq] by a rust binary called
the proxy. It uses [warp][wa] to serve a [Juniper][ju] powered API providing all necessary
queries and mutations.

For dependency management and execution of common tasks we use [Cargo][co]. To
get up to speed with common functionality and manifest file intricacies consult
the exhaustive [Cargo Book][cb].

The proxy binary's lifecycle is managed by the main renderer of the UI in:
`native/main.js`. When running `yarn dist` it is bundled together into an
Expand All @@ -422,7 +426,7 @@ application package by [electron-builder][eb].

### Running the proxy in stand-alone mode

To start the proxy binary, run: `cd proxy && cargo run -- --source=memory`.
To start the proxy binary, run: `cd proxy && cargo run -- --registry=emulator`.
After that the GraphQL API is served on `http://127.0.0.1:8080/graphql`.


Expand All @@ -436,11 +440,72 @@ git submodule update --init --remote
git submodule foreach "git fetch --all"
```

Then run tests as usual: `cargo test`.

💡 *You'll have to run the submodule commands every time there are any updates
to the test fixture repository.*

Then run tests as usual: `cargo test --all-features --all-targets`.

We strive for two kinds of tests: classic unit tests contained in implementation
files and integration tests. The integration tests are meant to assert correctness
of the API provided by the proxy, these can be found under `proxy/tests`. To find
out where to place and how to lay out tests, check the Rust book [test chapter][rt].

### File structure

The GraphQL API exposes the application's domain logic. Therefore we try to treat
it as a thin layer exposing well-typed entities. The heavy lifting is done in the
modules named after the protocols we consume - [radicle-link][rl] through it
[radicle-surf][rs], for code collaboration and [radicle-registry][rr] for global
unique entries for users, projects and organisations. By isolating concerns this
way, we hope to enable ease-of-contribution to downstream teams. Empowering them
to reflect changes in their public APIs easily with code contributions to Upstream.

```
proxy/src/
├── coco.rs
├── env.rs
├── error.rs
├── graphql
│   ├── api.rs
│   ├── error.rs
│   ├── project.rs
│   └── schema.rs
├── graphql.rs
├── lib.rs
├── main.rs
└── registry.rs
```

## Scripts

To get a list of all available script commands, run: `yarn run`.
NunoAlexandre marked this conversation as resolved.
Show resolved Hide resolved
Here is a list of the most commonly used ones:

```sh
yarn start # Start Upstream in development mode

yarn test # Run Cypress end-to-end tests
yarn test:debug # Show the Cypress GUI, handy for visual debugging

yarn dist # Bundles Upstream into an installable package

yarn generate:colors # Update color CSS variables in public/colors.css from
# colors.json

yarn graphiql # Open GraphiQL with explorer extension in browser

yarn release # Start a two-step process to cut a new release, for more
# details have a look at ../DEVELOPMENT.md

yarn prettier:check # Check UI code formatting
yarn prettier:write # Auto-format UI code
yarn lint # Check UI code for linting errors

yarn proxy:build # Build the proxy binary
yarn proxy:build:release # Build the release version of the proxy, stripped of debug symbols
yarn proxy:start # Start only the proxy with its default configuration
yarn proxy:start:test # Start the proxy in test mode, where state is isolated and lives in memory or temporary directories
```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We also have a bunch of helper scripts for the proxy in our package.json, should we maybe include those here too with proper descriptions?

proxy:build          # cd proxy && cargo build --all-features --all-targets
proxy:build:release  # cd proxy && cargo build --release --all-features --all-targets
proxy:build:test     # cd proxy && cargo test --no-run
proxy:start          # cd proxy && cargo run --release -- --registry=emulator
proxy:start:test     # cd proxy && cargo run -- --registry=emulator --test

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Generally I find these outputs of cli options to be prone to quickly get outdated. I'd rather show a command which shows all the commands.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know what you mean. This section expands a bit on the commands however. It's meant to explain when they should be used. As the yarn run command can only show the commands themselves, but there is no way to inline documentation in package.json.

I just provided the # cd proxy && cargo run comments as a reference, the idea was that you'd write the explanation in a comment...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed in 4b037b7


## CI setup

Expand Down Expand Up @@ -549,18 +614,27 @@ Release v0.0.11 successfully completed! 👏 🎉 🚀

[ar]: https://buildkite.com/monadic/radicle-upstream/builds?branch=master
[bk]: https://buildkite.com/monadic/radicle-upstream
[cb]: https://doc.rust-lang.org/cargo/
[cc]: https://www.conventionalcommits.org/en/v1.0.0
[cl]: https://gist.github.com/Rich-Harris/0f910048478c2a6505d1c32185b61934
[co]: https://github.com/rust-lang/cargo
[cs]: https://help.github.com/en/github/authenticating-to-github/signing-commits
[eb]: https://github.com/electron-userland/electron-builder
[el]: https://www.electronjs.org
[ge]: https://github.com/OneGraph/graphiql-explorer
[gc]: https://cloud.google.com/sdk/docs/quickstart-macos
[ge]: https://github.com/OneGraph/graphiql-explorer
[gs]: https://github.com/OneGraph/graphiql-with-extensions
[gq]: https://graphql.org/
[hb]: https://github.com/github/hub
[hu]: https://github.com/typicode/husky
[ju]: https://github.com/graphql-rust/juniper
[ls]: https://github.com/okonet/lint-staged
[pr]: https://prettier.io
[rl]: https://github.com/radicle-dev/radicle-link
[rr]: https://github.com/radicle-dev/radicle-registry
[rs]: https://github.com/radicle-dev/radicle-surf/
[rt]: https://doc.rust-lang.org/book/ch11-01-writing-tests.html
[se]: https://svelte.dev
[sv]: https://github.com/conventional-changelog/standard-version
[tp]: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
[wa]: https://github.com/seanmonstar/warp
1 change: 0 additions & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,6 @@
"svelte:watch": "yarn svelte:clean && rollup -c -w",
"proxy:build": "cd proxy && cargo build --all-features --all-targets",
"proxy:build:release": "cd proxy && cargo build --release --all-features --all-targets",
"proxy:build:test": "cd proxy && cargo test --no-run",
"proxy:start": "cd proxy && cargo run --release -- --registry=emulator",
"proxy:start:test": "cd proxy && cargo run -- --registry=emulator --test",
"graphiql": "open http://localhost:5000",
Expand Down