naming-conventions.md

General

Types/Interfaces:

Note: While this one allows for freeform, I think we should err on the more is more approach. Explanations that explain what the object is in our domain would be more useful, especially for some of the cumbersome types. That said, some types are rather self descriptive, and in those cases, we should opt for the Represents format.

Represents a (SimpleExplanation!).

• Represents a (Git commit).
• Represents a (triggered deployment instance).
• Represents a (comment on an Gist).
• Represents a (Git tree).
• Represents a (team discussion).

(Freeform!).

• A label for categorizing Issues or Milestones with a given Repository.
• Projects manage issues, pull requests and notes within a project owner.
• An emoji reaction to a particular piece of content.
• A user is an individual's account on GitHub that owns repositories and can make new content.
• A repository-topic connects a repository to a topic.

Unions:

Types that can be (UnionDescription!).

• Types that can be (inside Project Cards).
• Types that can be (results of a search).
• Types that can be (an item in an pull request timeline).
• Types that can be (an item in an issue timeline).
• Types that can be (inside a Milestone).
• Types that can be (requested reviewers).
• Types that can be (an actor).

Enums:

Properties by which (Object!) lists can be ordered.

• Properties by which (milestone) lists can be ordered.
• Properties by which (gist) lists can be ordered.
• Properties by which (language) lists can be ordered.

The possible (PluralProperty!) of a (Object!).

• The possible (states) of a (deployment).
• The possible (states) of a (milestone).
• The possible (states) of an (issue).
• The possible (invitation roles) of an (organization).
• The possible (roles) of a (team member).
• The possible (affiliation levels) of a (subject).

The possible (PluralProperty!) a (Object!) (Condition!).

• The possible (reasons) a (repository) (could be in a locked state).
• The possible (reasons) a (repository) (is listed as 'contributed').
• The possible (reasons) a (suggested topic) (is declined).

Enum Values:

Order (PluralObject!) by (Property/DynamicProperty!).

• Order (gists) by (creation time).
• Order (languages) by (the size of all files containing the language).
• Order (teams) by (name).
• Order (milestones) by when they are due.

The (Object!) (State!).

• The (project) (is open).
• The (issue) (is open).
• The (pull request) (has been closed by being merged).
• The (pull request) (can be merged).
• The (status) (is errored).

(Freeform!).

• The suggested topic is too general for the repository.
• Author has previously committed to the repository.
• The issue or pull request was locked because the conversation was spam.

Queries

Single Record Query:

Fetch a (Object!) by its (Property!).

• Fetch a (Marketplace category) by its (slug).
• Fetch a (Marketplace listing) by its (slug).
• Fetch an (object) by its (ID).
• Fetch a (repository owner) by its (login).
• Fetch a (topic) by its (name).

List Query:

Fetch a list of ((Adjective/TransitiveVerb) PluralObject!).

• Fetch a list of (Marketplace listings).
• Fetch a list of ((alphabetically sorted) Marketplace categories).

Generic Query:

(Freeform!).

• Return information about the GitHub instance
• Perform a search across resources.

Argument Descriptions:

Single Record Identifier:

The (Object!)'s (Property!).

• The (code of conduct)'s (key).
• The (license)'s (downcased SPDX ID).
• The (category)'s (URL slug).
• The (organization)'s (login).

Boolean:

Filter to ((Adjective/Noun) PluralObject!) (FilterSpecification).

• Filter to (categories) (with listings).
• Filter to (listings) (to which viewer has admin access).
• Filter to ((child) teams).

Generic Argument:

(Freeform!).

• (Select only listings with the given category).
• (The name of the repository).
• (The login field of a user or organization).
• (The types of search items to search within).
• (The topic's name).
• (Allows filtering Reactions by emoji).
• (Filters history to only show commits with matching authorship).
• (Allows specifying a beginning time or date for fetching commits).

Field Descriptions:

Boolean:

(CurrentObject!)! (Condition!) (Context).

• (Organization) (is adminable) (by the viewer).
• (Progress item) (is completed).
• (Growth agent prompts) (are shown) (on the growee's home).
• (Champion) (has white label client).
• (Champion) (should display only owned content) (in Discover).
• (User) (has confirmed account).
• (Connection) (can be disconnected) (by the viewer).

List Association Field:

The ((Adjective) PluralRelatedObject!) (RelationToCurrentObject!) (Context).

• The (users) (following this champion).
• The (posts) (in this channel).
• The (collections) (owned by this champion).
• The ((available) topics) (for this champion) (during content creation).

Single Record Association Field:

The (RelatedObject!) (RelationToCurrentObject!).

• The (Repository) (that this commit belongs to).
• The (actor) (that owns the gist).
• The (repository) (associated with this milestone).
• The (repository) (associated with this label).
• The (actor) (that authored the comment).

Generic Field:

The (Explanation!).

• The (status information for this commit).
• The (HTTP path for editing this team).
• The (title of the release).

Types

• Do we want to have descriptions for each field on the types? If so, how do we want to handle the fact that we haven't re-mapped any of the Rails names in the type fields? (e.g. Organization.allowChampionOnboarding)

Arguments

We definitely need to flesh out more cases for args like:

• pagination args
• sort and order values
• Dealing with our arg naming rules (byType, withType, onlyType, etc.)

Payloads

We need a standard for all the payloads. All errors should have the same description and things like success and type (e.g. groupSpace) should also have a standard description