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).

follow a format like Represents an (Object!). (Simple Explanation).

I feel like that would force an unnecessary prefix when you want to use a more verbose explanation. I'm fine if that's what we all agree on, but it feels awful redundant.

I'm confused about the enums and their values being described for ordering.

This has to do with all the new sort enums that I just put in place. That example was meant to represent how we'd have a common naming convention for all Enums that are used for sorting.

How should we describe enums like OwnerType, which is just a list of types?

This one fits into the second format that I have specified there: "The possible types of an Owner"

For list queries, what is the use case for adding an adjective or transitive verb to the description?

The use case would be for things like "active", "most recent", etc. Things that aren't part of the object type but describe the sub-filtering that was applied to the object type.

In general, I think we need more discussion around how to describe arguments

I'm good with that. This document wasn't meant to be the end-point but rather a jumping off point for us.

For list association-fields, how do you want to deal with polymorphism?

We should use the polymorphic type name as the Object in that scenario.

I would also like the description for single record argument identifiers - The (Object!)'s (Property!).

That makes sense. We can have that be the default, allowing for custom ones if needed.

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