Skip to content

Enforce `.` at end of GraphQL descriptions

Luke Duncalfe requested to merge ld-graphql-description-cop-periods into master

🎗 Note to maintainer

When merging, please MWPS, and please post to #backend_maintainers recommending that everyone MWPS rather than just straight merge any GraphQL changes on the day. This should avoid this new cop breaking master.

What does this MR do?

Our current GraphQL style guide states that description strings should not end in periods. Unfortunately this is different from the style that the ruby-graphql library follows where description strings for the scalars, connections and other objects it supplies all do end in periods (example). This makes our overall API inconsistent in how it presents its schema descriptions.

This MR:

  • changes our GraphQL API description style guide to recommend that we add periods to the end of description strings.
  • adds to the existing GraphQL/Descriptions cop to enforce this.
  • changes the part of the app that generates descriptions when deprecating a field to add periods to the end of the description string.

An alternative to this approach would be to add code to our base objects (BaseField, BaseConnection, etc) to test the given description string arguments during initialisation and add a period to the end if one is missing. I've chosen the approach of instead enforcing the style with a cop as it makes our codebase consistent and hopefully reduces the possibility of the topic arising during review-time.

#292426 (closed) will track the progress of fixing the existing offenses.

Does this MR meet the acceptance criteria?

Conformity

Availability and Testing

Edited by Luke Duncalfe

Merge request reports