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

A few thoughts:

General

• I feel like the types and interfaces should follow a format like Represents an (Object!). (Simple Explanation). That way it works for simple descriptions like Represents a User, but can also be clarified like Represents a UserToDoList, which join users with ToDoLists.
• I'm confused about the enums and their values being described for ordering. Can you provide a use case for this? It seems like if we have an enum for a query, it's used for filtering rather than ordering. Also, what to do about enums that are both defining a property for an object as well as defining a possible list of filters for a list query, like ArtifactableType?
• How should we describe enums like OwnerType, which is just a list of types? It seems like the rule for the enum should be something like The possible types that can be a (enum description) => The possible types that can be an owner. And the rule for the values could simply be A (type) => A champion.

Queries

• For list queries, what is the use case for adding an adjective or transitive verb to the description? Is that potentially for default sort? If that's the case, I would prefer to capture that perhaps in parentheses if the behavior is out of the ordinary, like A list of marketplace categories (sorted alphabetically by default).

Arguments

In general, I think we need more discussion around how to describe arguments considering that we have some explicit rules about how to name query args themselves in GraphQL. For example, when we're talking about booleans, we can talk about either a boolean argument that filters the list of records by some condition (progressItems(onlyCompleted: Boolean)) or we can talk about a boolean field (trees(inMarketplace: Boolean)). To me, it makes sense to have distinct descriptions for these two, something like Filter to (PluralObject!) that are (FilterSpecification!) => Filter to progress items that are completed vs. Filter to (PluralObject!) where (Field!) is true or false => Filter to Trees where inMarketplace is true or false.

Just off the top of my head, there are other instances where we should be more explicit about how to describe arguments. Like if we're describing an argument that filters by field, there should be a rule like Filters (PluralObject!) by (Field!) => Filters scales by scaleType.Or if we want to describe an argument that filters records with some related object, we should have a rule like Filters to (PluralObject!) that have (RelatedObject/description of relation!) => Filters to posts that have an attachment, like links or artifacts.

etc...

Field Descriptions

• For list association-fields, how do you want to deal with polymorphism? Would you prefer to keep the same template and list all possible objects, like The Trees and Collections for this Champion? Or would you prefer to replace the object with the polymorphic type, like The content items for this Champion?
• Similarly, for single record association-fields, how do you want to deal with polymorphism? Would you prefer to keep the same template and list all possible objects, like The User or Champion that owns this Collection? Or would you prefer to replace the object with the polymorphic type, like The owner of this Collection?
• I would also like the description for single record argument identifiers - The (Object!)'s (Property!). - to also be used for obvious field descriptions. I realize this ventures into the territory of having judgment calls about what's obvious, but I would like to have some consistency for things like The Champion's name or The Collection's description

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