Show deprecation information in the Docs sidebar

[davidcelis]

The GraphQL specification states clearly:

Tools built using GraphQL introspection should respect deprecation by
discouraging deprecated use through information hiding or
developer‐facing warnings.

Currently, however, GraphiQL doesn't give any indication of whether or
not a field or enum value is deprecated. This patch rectifies this by
adding some red text next to field names and enum value names that just
says "(DEPRECATED)". If a deprecation reason is given for a field or
enum value, that is rendered (also in red) underneath the field or
value's description.

Closes #34.

Signed-off-by: David Celis davidcelis@github.com

[facebook-github-bot]

Thank you for your pull request and welcome to our community. We require contributors to sign our Contributor License Agreement, and we don't seem to have you on file. In order for us to review and merge your code, please sign up at https://code.facebook.com/cla - and if you have received this in error or have any questions, please drop us a line at cla@fb.com. Thanks!

[davidcelis]

Signed the CLA! A couple of notes about this patch also 😄

1. I ended up re-using the Description component to render a deprecation reason. It seemed like another good use-case so I hope that's okay but, if not, let me know and I'm happy to make a new component.
2. I didn't add any tests, but it seems like the markup isn't generally tested. I may have missed something, so if there are tests I should be adding, let me know!
3. I'd also really love to visually alter requested fields in the query editor if they're deprecated. I looked through some of the CodeMirror stuff but I just couldn't figure out where field validation was happening 😓 If someone could point me in the right direction there, I can add another patch to this PR ✨

[ghost]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Facebook open source project. Thanks!

[asiandrummer]

Hi @davidcelis - thanks for contributing!

I ended up re-using the Description component to render a deprecation reason.

I think it's fine, although I'd like Description component to be called differently as it's really just a component that can hold markdown texts I feel like. Either that or we could just create another component that even defaults the style to use alert text:

<DeprecatedReason markdown={field.deprecatedReason} />

I'm personally more attracted to the first approach of changing the component name.

I didn't add any tests, but it seems like the markup isn't generally tested.

My long-awaited goal... :p Would you be interested in becoming a pioneer and write tests for this?

I'd also really love to visually alter requested fields in the query editor if they're deprecated.

This would be a bit tricky since the styling in QueryEditor is determined by the style token passed in from online-parsing the document, which is defined in codemirror-graphql repo. When you mention "field validation", I'm guessing you meant how CodeMirror uses the parsed document/AST from codemirror-graphql online parser and figure out how to treat/style each token. It's pretty straightforward to modify token context passed in from the online parser and add a new style to reflect that new style context, but I'm in process of moving the language service portion as a separate repository - I can take care of this after that.

A workaround to make this happen would be creating a new style in codemirror.css and manually attach it to components' classNames prop to style deprecated fields/values for now, and remove this once the process becomes organic like described above. I'd be down for this approach since I'm pretty horrible with making the styling look good and would love to get some help from you :D

[asiandrummer]

Just a small nit: I'd like to keep the brackets open/close using its own line

{
  field.isDeprecated &&
  <span ... />
}

[davidcelis]

@asiandrummer Thanks for the comments!

Just a small nit: I'd like to keep the brackets open/close using its own line

Done in 8cd42bc 😄

I'd like Description component to be called differently as it's really just a component that can hold markdown texts I feel like.

Agreed. I've renamed it to MarkdownContent but I can change it to something else too if that doesn't quite fit the bill.

I'm in process of moving the language service portion as a separate repository - I can take care of this after that.

A workaround to make this happen would be creating a new style in codemirror.css and manually attach it to components' classNames prop to style deprecated fields/values for now, and remove this once the process becomes organic like described above.

I can try out a workaround, but it sounds like we'll be able to take care of this in a better way once the language service portion is moved out. I'm happy to help with the visual alteration once that happens! I was thinking a strikethrough would be a good way to denote deprecation.

Would you be interested in becoming a pioneer and write tests for this?

I'm happy to lay some foundations for this, though I should probably also say that this is my first contribution to a React application. So that might take some extra time to learn how to do this 😄

[asiandrummer]

Love the changes - would you mind squashing commits into a single one if possible?
Unless you'd like to tackle the above couple of things (tests/query editor visual changes), I'm ready to merge it after commit squashing!

[davidcelis]

Squashed!

[Globegitter]

@davidcelis how exactly is this supposed to look like? I just upgraded and added a deprecated field. I am seeing the deprecation text in red when I click on the field but I am not seeing anything in the overview, where I have the list of field. Is that as expected?