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

Changes from 3 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
110 changes: 76 additions & 34 deletions DEVELOPMENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -374,39 +374,16 @@ 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`.
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
```


## 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 managament and execution of common taks we use [Cargo][co]. To
xla marked this conversation as resolved.
Show resolved Hide resolved
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 @@ -415,7 +392,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 @@ -429,12 +406,71 @@ git submodule update --init --remote
git submodule foreach "git fetch --all"
```

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

We strive for two kind of tests, the classic unit tests inside of the
xla marked this conversation as resolved.
Show resolved Hide resolved
implementation files. Additionally we have a suit of integration tests esp. to
assert the API the proxy provides from a high-level consumer perspective, these
can be found under `proxy/tests`. To find out where to place and how to layout
tests check Rust book [test chapter][rt].
xla marked this conversation as resolved.
Show resolved Hide resolved

### File structure

We understand the GraphQL API as one potential surface to expose the
xla marked this conversation as resolved.
Show resolved Hide resolved
Application 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
xla marked this conversation as resolved.
Show resolved Hide resolved
protocols we consume - `CoCo` for code collaboration and `Registry` for global
xla marked this conversation as resolved.
Show resolved Hide resolved
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
```

💡 *You'll have to run the submodule commands every time there are any updates
to the test fixture repository.*
xla marked this conversation as resolved.
Show resolved Hide resolved


## 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
```
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

Our CI infrastructure runs on [Buildkite][bk]. The build process is run for
Expand Down Expand Up @@ -542,18 +578,24 @@ 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
[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