Commands like check, push, etc. that use SDL should be able to take stdin like so

echo "type Query { hello: String }" | rover schema push --graph-name test

I am opening this issue to have a discussion about our future intentions with .config file. A few points of consideration that were previously brought up in env var PR comment:

1. Are we aware of other Apollo tools using config directories? It will be good to synchronise with other teams to make sure we don't have too many directories in users' systems belonging to Apollo.

2. Are we 100% sure on the locations of the config directory? (The answer could be 'yes'). To recap, current locations are:

   // Lin: /home/alice/.config/rover
   // Win: C:\Users\Alice\AppData\Roaming\Apollo\Rover\config
   // Mac: /Users/Alice/Library/Application Support/com.Apollo.Rover

   I would usually expect Mac's config directory to be exactly like Linuxes in this case. I've currently got a bunch of CLI's sharing the .config directory, for example:

   ₍ᐢ•ﻌ•ᐢ₎*･ﾟ｡ .config  ✿ ls -l
   total 8
   drwxr-xr-x  4 lrlna  staff  128 22 Sep  2017 bankai
   drwx------  9 lrlna  staff  288  9 Dec 16:44 configstore
   drwx------  4 lrlna  staff  128  3 Apr  2016 fish
   drwx------  3 lrlna  staff   96 28 Jun  2017 gtk-2.0
   drwx------  3 lrlna  staff   96  6 Apr  2016 htop
   -rw-------  1 lrlna  staff  100 23 Dec  2016 hub
   drwxr-xr-x  5 lrlna  staff  160 21 May  2016 learnyounode
   drwxr-xr-x  3 lrlna  staff   96 21 May  2016 workshopper 

   Usually things that live in Library/Application Support tend to be Applications, and as far as I understand, Rover is not bundled as an application.

Depending on what people think, we can also leave everything as is. I simply want us all to agree and sign off on this as to avoid as much settings migration work in the future as much as possible.

(Just to be clear, this is not about the error condition output but --help)

Currently, the first line of the --help output appears as <app_name>-<sub_command>-<sub_sub_command> <version>. For example, for rover partial delete --help:

$ rover partial delete --help
rover-partial-delete 0.0.1-rc.0
🗑  Delete an implementing service and trigger composition

USAGE:
... snipped for brevity ...

While I could certainly understand the value of having the version in the output here, particularly for error conditions when it would be nice to see in continuous integration logs or something what version, I find that this particular usage in --help muddles up the preamble of this output by including this initial line. I'm not sure what rover-partial-delete adds in terms of value. If it's not important, I might suggest adding the version as the very last thing in the --help output.

(Separately, we might want to consider adding the version to the error output, which currently doesn't contain either <app_name>-<sub_command>-<sub_sub_command> <version> or the version.)

Tagging this as a question for now!

• build releases

requirements:

• must be able to opt out with APOLLO_TELEMETRY_DISABLED environment variable.
• must report the following info on every command:
  • the command that was run
  • the operating system that the command was run on
  • information about the CI system being used, if it can be detected
  • a machine ID generated once per dev machine
  • the version of rover the command was executed on

should we also collect the following info?

• session id, a uuid for each command that is run
  • this was included in the first pass at telemetry, but doesn't seem particularly useful unless we need to use them to index in bigquery or to differentiate between different otherwise identical events
• command results
  • im thinking we should report error rate vs panic rate vs success rate by reporting information kinda like this (i have it in json for now just for readability)

on success:

success: true

on error:

success: false,
failure: {
  "type": "error",
}

on panic (would be std::panic::PanicInfo):

success: false,
failure: {
  "type": "panic",
  "location": {
    "file": "src/cli/power.rs",
    "line": 12
  },
}

Originally from #108 (comment)

When a graph push or subgraph push fails, we don't really have any context beyond the plain text that studio returns. It looks like:

Error: Failed while pushing to Apollo Studio. To see a full printout of the schema attempting to push, rerun with `--log debug`

Caused by:
    encountered a GraphQL error, registry responded with: Could not parse as a GraphQL schema. Are you sure that your proposed schema is a parsable GraphQL schema?

It'd be nice to have a more custom error experience here, with more instructions

As of https://github.com/apollographql/rover/releases/tag/v0.0.1-rc.0 there are variations in the way that "graph + variant" are provided as rover parameters. For example, the rover schema fetch command expects a <GRAPH_NAME> positional parameter with a --variant flag:

$ rover schema fetch
error: The following required arguments were not provided:
    <GRAPH_NAME>

USAGE:
    rover schema fetch <GRAPH_NAME> --log <log-level> --profile <profile-name> --variant <variant>

... while the rover partial delete command expects a --graph-name and a --graph-variant as flagged parameters (with no positional parameters):

$ rover partial delete
error: The following required arguments were not provided:
    --graph-name <graph-name>
    --service-name <service-name>

USAGE:
    rover partial delete --graph-name <graph-name> --log <log-level> --profile <profile-name> --service-name <service-name> --variant <variant>

... and the rover schema push command (which is in the same subcommand categorization as rover schema fetch in the first example from above), expects similarly flagged parameters but a <SCHEMA_PATH> as the lone positional parameter:

$ ./target/debug/rover schema push --help
rover-schema-push 0.0.1-rc.0
⬆️  Push a schema to Apollo Studio from a local file

USAGE:
    rover schema push [OPTIONS] <SCHEMA_PATH> --graph-name <graph-name>

I actually believe that rover schema fetch is the outlier here but, if <graph-name> is as important as I think it is to most of the commands in the partial and schema commands, I would claim that it should be the model and that we should always have the <graph-name> as the first positional parameter.

Thoughts? Discussion? (If this issue is closed and we resolve this later, we should at least align on one pattern, which I think means fixing rover schema fetch.)

rover whoami should print out information about the currently authenticated user.

it should take a --profile flag so it can print out information about all different profiles.

it should at the very least print out a username and email, and it should also likely print out information about the scope of the token that the user is authenticated with.

description edited by @EverlastingBugstopper

it_lists_nothing_when_no_profiles fails occasionally. probably a race condition. example of failure: https://github.com/apollographql/apollo-cli/runs/1125449016?check_suite_focus=true#step:6:90

As part of establishing the relationship with the registry, and also just as a bit of satisfying detail / helpful information, it would be great if — when publishing a schema (new, or otherwise) to the registry — we could show a simple delta of the changes:

Published my-graph#282ef2 [+2 types, -5 types, +8 fields, -10 fields] 

I'm not sure if an API is exposed that reveals anything like this right now, but I suspect the Cloud team would be amenable to adding it.

right now it's required to have a $VERSION variable set before the curl installer works. this should be set automatically either in our release process by parsing from Cargo.toml, or by the installer itself checking for $VERSION and then making a separate HTTP request to figure out the latest version released on github. i'm not sure which one i like better, the first one is more performant (eliminates one round trip to github), whereas the second one might be a bit easier.

edit: i'd like explicit approval for the plan outlined in this comment from the following folks 😄

• @ashleygwilliams
• @JakeDawkins
• @jbaxleyiii

we need to decide how to structure our changelog and how much (if any) help we want from automation.

i think we've already implicitly decided this but i want to make it explicit here: we will have the entire changelog >= 0.1.0 in CHANGELOG.md at the root of this repository, and it will include changes to rover and also the other crates in the workspace (currently Apollo/Houston). Additonally, for each release, that section of the changelog will be put in the body of the GitHub release.

possible structures for the changelog:

• the one we used for Wrangler: https://github.com/cloudflare/wrangler/blob/master/CHANGELOG.md. it has a section for each release, and subsections for fixes, features, maintenance, and documentation. each entry links to an issue, a pr, and an author. each changelog entry is written manually and attempts to give some context and links to docs where appropriate.
  • pros:
    • me and @ashleygwilliams are already familiar with it
    • it is chocked full of information separated into logical chunks
  • cons:
    • i don't think it's based on any standard
    • no automation has been written for this structure except this VS Code snippet
• keepachangelog.com:
  • pros:
    • it's more standardized than the wrangler approach
    • it suggests maintaining an Unreleased section so folks can keep up with what is being worked on/coming in the next release
    • it's going to be easier to automate for since it follows a standard (we could use this library)
    • there's also this GitHub action that could auto-generate changelogs based on different GitHub APIs. It seems fairly flexible, but likely very opinionated and I'm not sure how easy it would be to edit the changelogs it generates. My guess is we'd want to go with our own tool that uses the aforementioned library.
  • cons:
    • i'm not sold on the "added, changed, removed, fixed" sections as logical groupings and much prefer the "features, fixes, maintenance, and docs" separation from the first option
• auto-generated changelog from commits
  pros:
  • less writing for us!
    cons:
  • requires commits to have meaningful messages (good practice but hard to enforce)
  • lets not do this one, it's not a real suggestion

each of these structures could be combined as well! i can see a world where we choose to keep the general layout of wrangler's changelog, and try to contort it in a way that works well with the keepachangelog library that would help with automation (this is what i'm leaning towards at the time of writing).

like i said earlier, what we should definitely do is make sure that CHANGELOG.md is up to date on main before tagging a release and kicking off the GitHub action. This makes it so either the person cutting the release can easily copy and paste into the GitHub release body, or we can configure the GitHub action to do it automatically (my preference).

there are a few different approaches we could take to get CHANGELOG.md up to date on main:

• manually write the changelog right before the release and commit it as part of the release PR
• manually write the changelog as part of every PR before it is merged to main (could combine this with a bot that checks to see if there is an entry on the PR)
• have a bot make a PR against every PR that adds a changelog entry to CHANGELOG.md based on the linked issues and the PR description (interesting, but probably a lot of engineering work. there may be a tool to do this already but i couldn't find anything with a super dedicated following).

i'm really interested in thoughts here and also some other approaches that I haven't yet considered!

While today, the GitHub Releases act as the source of truth for our builds, in the event of a GitHub outage this could be a liability. We can mitigate against this by publishing them to a secondary cloud storage location (e.g., Amazon S3, Google Cloud Storage) by merely doing an (e.g., again) aws s3 cp artifacts*.* s3://our-backup-bucket or gcs cp artifacts.* our-backup-bucket (these may not be technically accurate examples, but hopefully you get my point) using the appropriate tool and credentials.

when running rover subgraph push, it is possible (and likely!) that you will get composition errors.

currently these are printed as so:

    if let Some(errors) = response.composition_errors {
        tracing::error!(
            "The following composition errors occurred: \n{}",
            errors.join("\n")
        );
    }

there isn't any guidance as to how these composition errors should be resolved as part of the normal workflow. i'm not sure what exactly resolving composition errors actually looks like, and I believe we will need to educate our users on this as well.

let's discuss!

we need docs for the rover graph fetch command that was introduced in #23 :)

right now, running rover --help or rover prints the following:

$ rover --help
Rover 0.0.0
✨🤖🐶 the new CLI for apollo

USAGE:
    rover <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    config    ⚙️  Manage configuration
    help      Prints this message or the help of the given subcommand(s)
    schema    🧱 Fetch a schema

I think it would be a great idea to have a bit of front matter that can help folks with progressive discovery of the functionality Rover provides. Not sure exactly what it would look like (especially given the early stage of development), but I'm thinking something along these lines

$ rover --help
✨🤖🐶 Rover - the new CLI for apollo

To begin working with Rover, run the 'rover config api-key' command:

    $ rover config api-key

This will prompt you for an API Key that can be generated in Apollo Studio.

The most common commands from there are:

    - rover schema push : Push a GraphQL schema to Apollo Studio
    - rover schema get    : Pull a GraphQL schema from Apollo Studio

You can find documentation for Rover here: https://docs.apollographql.com/rover

USAGE:
    rover <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    config    ⚙️  Manage configuration
    help      Prints this message or the help of the given subcommand(s)
    schema    🧱 Fetch a schema

• Might include link to documentation on each command?

This is maybe a somewhat selfish ask for internal use, but since we are using the staging API for our own graph, all of the commands that have studio.apollographql.com hardcoded have to be massaged for us to use them. For instance

APOLLO_REGISTRY_URI=https://graphql-staging.api.apollographql.com/api/graphql rover config api-key                                                       
  INFO Go to https://studio.apollographql.com/user-settings and create a new Personal API Key.
  INFO Copy the key and paste it into the prompt below.

Could we respect the APOLLO_REGISTRY_URI everywhere and use it for the URLs that we spit out? Also (perhaps worthy its own issue) it'd be nice if we could embed the APOLLO_REGISTRY_URI in a profile to avoid needing to always add it to commands!

• contribution policy
• license
• badges

Just an issue to log any feedback from the rename from schema -> graph and partial -> subgraph from #103

Definitely a duplicate of #99, but I'm going to close that since there is discussion here 🙃

The schema fetch command requires the graph id to be passed as a positional arg, where the other commands like push require it be passed as a flag --graph-name.

rover schema fetch [OPTIONS] <GRAPH_NAME>
rover schema push [OPTIONS] <SCHEMA_PATH> --graph-name <graph-name>

Maybe we should rethink what things we pass as positional args vs which are passed as flags.

Maybe it's not a big deal that we pass graph-name as a flag one place and a positional arg in other places. If people think that, feel free to say so! I'll provide some options in design below if you do agree that we need to make it consistent

when we announce the 0.1.0 release candidate we should have a set of instructions to help folks explore the new features of the release. this is our first release so there will be a fair amount to explore.

We have a graph fetch command right now to download sdl of a full schema from the registry.

I'd like there to be a similar command for fetching a subgraph with a service name. This could be useful, for example, to download a subgraph to push to another graph??

Questions:

• Should we also allow downloading the full composed graph? I think so, right?
  • I think we could support that by either educating people to use graph fetch on the federated graph or making the service name optional, and downloading the whole graph if omitted

to reproduce try to delete a profile without having created a profile in the first place.

we should be handling the error types themselves in houston and providing an actionable message directly in rover.

$ cargo run -- config profile delete dne 
Error: No such file or directory (os error 2)

• test rust stable
• test rust nightly
• run fmt + clippy

As a part of #39, we changed how docs are deployed from this repo, but didn't catch the old github action that deployed the gitbook in the past, so that action still fails on main.

We need to remove this: https://github.com/apollographql/rover/blob/main/.github/workflows/docs.yml

it_can_list_one_profile is failing, looks like the problem is that the write_stdin function on the api key command just... doesn't take the input properly and makes rover config api-key fail in tests.

edit: it looks like the problem is that the read_secure_line() function that we use to write the API key to the file will just return an empty string if it detects that stdin is not coming from the terminal. so we may need to add support for an API key or use some other way of reading from stdin that doesn't check if it's actually coming from a terminal.

or since what we're testing here is the list functionality, just manually create the file that list is looking for

Right now, we've been hand-writing usage docs for the CLI. I think it'd be nice for the sake of kepping these docs in sync if we could generate docs which are just a printout of the --help output, and work to make sure that output is usable and beautiful.

Currently, if you try to perform an action on a graph that does not exist (or could not exist), rover will output a generic error message (e.g. Error: Failed while fetching from Apollo Studio). Instead, I think we could probably handle a few error cases that users are likely to run into:

• Fetching a graph using an illegal name (e.g. _0tu23- or foo@bar)
  Users might run into this because they're trying to use ${graph}@${variant}, and we could even catch the @ symbol in particular and recommend --variant. The regex we use for graph IDs in Studio is this: [a-zA-Z][a-zA-Z0-9_-]{0,63}

• Fetching a graph that you do not have access to / does not exist
  We cannot differentiate between "that graph does not exist" and "you do not have access to that graph," but we can tell a user that either the graph does not exist or their credentials do not permit access by seeing if data.service is null

Right now, most of the rover-client public run functions accept a client: StudioClient. This transfer of ownership from the caller to the run function means we can't reuse the same client in the command files if we want to.

I've already made the change to &StudioClient in the partial delete code #84, but I think we should do it everywhere for consistency

After some discussion with @StephenBarlow, we realized that it is quite difficult to find emojis that work well cross-platform (with Windows giving us quite a bit of trouble).

We still think that it's nice to have a splash of color in your terminal, and emojis are a great way that we can add some character to Rover. However, coming up with a new emoji for each subcommand, making sure that it looks nice cross-platform, and that they don't mess up spacing (some emojis are more unicode characters than others which can affect render width) is a bit too high of a cost.

I proposed that instead of emojis for each subcommand, we replace the INFO, ERROR, WARN, TRACE, and DEBUG log messages with emojis for each one. The thinking here is that there are only five log levels, so it should be fairly straightforward to find nice cross-platform emojis, and also it shouldn't be hard to maintain since we won't need to add new ones in the future.

info: ℹ️
error: 🛑 or ❌
warn: ⚠️
trace: 🔍
debug: 🐛

(open to other suggestions ofc)

This decision is not final! Looking to gather some feedback here and gauge the temperature of the room.

lets make one as soon as we're ready to do our first release candidate.

should live in RELEASE_CHECKLIST.md and have instructions for creating a release from start to finish.

the readme should describe the project structure, it's goals + guarantees, and funnel people to the appropriate area of the project and/or project documentation.

Right now, we're kinda going with a barebones approach for what gets printed as the result of commands. This is fine for now, but we should standardize how results are printed and make sure it supports other output formats like JSON

Maybe a standard return from the run commands that gets passed to a parser/printer of sorts?

there should be a landing page which presents users with the installation instructions for their given platform (optionally showing other installation methods for other platforms)

these commands should be implemented in a way that is similar to what exists in the current CLI implementation and should not impact any live graph or schema in the registry.

should likely have a more concrete design proposal in this issue before any more serious work takes place

instead of using #[serde(skip_serializing)], we should have a way to denote that fields should be serialized, and by default they are not serialized.

i have some thoughts here but nobody seems to be taking the bait on this one - may end up being too complicated to implement.

In rover-client, the errors that'd be returned for invalid api keys (encountered a GraphQL error, registry responded with: 406: Not Acceptable) and invalid graph names (encountered an error handling the response: No service found) aren't very helpful or instructive.

#23 (comment)
#23 (comment)

we should change these errors to be more indicative of the actual problem, and provide a solution where applicable.

there should be a quickstart guide that guides users to install and perform one "hello world" workflow

The api-key subcommand allows you to configure a Rover profile. However, they are sibling subcommands at the moment, when we probably want to have the functionality live under profile.

I'm proposing we change authentication usage from the current world of rover config api-key to rover config profile auth. The thought is that this will communicate more clearly to end users that their API key is linked to a profile, and profiles can be managed with the other config profile subcommands.

I love the use of emojis in descriptions — I think it adds some personality into rover! In some places, though, emojis are separated from descriptions by a space and in others not. Also, some descriptions have an emoji, and some don't.

In particular, the top level descriptions are all missing a space between description & emoji and the others are not.

Somewhat of a nitpick, but could we make sure we have a space between every emoji & description and could we possibly add an emoji for the help text? I know that latter might be harder because it may be more baked into the library we're using...

We'd like the ability to configure what endpoint that rover's registry requests are made to. The default url would be to make requests to the prod url, but we'd like to be able to run operations against staging, etc. as well.

I think the profile, alongside the api key would be the perfect place for this

Currently, we have rover schema which represents a non-federated / complete graph which stands alone, and rover partial commands which represent pieces of graphs, when combined with other pieces and pushed into the registry, form a complete graph.

Opening this issue is largely in order to track the progress of that is unfolding elsewhere (apollographql/specs-join#1 (comment)) which suggests using subgraph, rather than partial.

Certainly opine on that issue if you have feelings about the specific naming, but let's keep this in mind.