Write contribution guide

[Anaminus]

Key points:

• No partial documents on master.
• Use branches for partial documents.
• Utilize pull requests for reviewing (works well with branches).
• Document and project stages.
• Refactor as a Manual of Style.
• Git crash course.
• Workflow with rbxapiref.

[Anaminus]

Added contribution document, as well as additional documents that describe other concepts.

[Anaminus]

Draft of document and entity states

Document and entity states

A document describes a primary entity, as well as a number of secondary entities. Each entity within a document has one of the following states of completeness:

• absent: The entity has no description within the document. The primary entity never has this state.
• dirty: The entity has a description, but the content is incomplete/unverified according to the document's current stage.
• pristine: The description of the entity is complete and verified according to the document's current stage.

Each document also has its own state:

• missing: There exists a primary entity, but the corresponding document file does not exist.
• draft: The document file exists, but contains one or more dirty entities.
• spotless: The document contains no dirty entities.
• perfect: The document only contains pristine entities.

Note that draft and spotless documents may contain absent entities. That is, a document does not need to contain every entity in order to be considered draft or spotless.

States are assigned in relation to the API. As long as it has a corresponding entity, a document "exists" even if it is not present in the repository. This is the meaning of the missing state.

When a primary entity receives an additional secondary entity (i.e. updated API), the pristine document corresponding to that entity will passively downgrade to spotless. This is due to the additional secondary entity having a state of absent.

Branches in the project repository may only contain documents of certain states.

[Anaminus]

With the above description, the current workflow looks something like this:

Branch	Allowed states
master	perfect, missing
(path)	perfect, spotless, missing
fork/PR	perfect, spotless, draft, missing

This is, however, flawed. Because perfect documents can passively transition into spotless, they cannot live on the master branch.

I propose to simplify the workflow so that spotless documents are allowed on master, and draft documents are allowed in branches:

Branch	Allowed states
master	perfect, spotless, missing
(path)	perfect, spotless, draft, missing
fork/PR	perfect, spotless, draft, missing

This allows members to push drafts directly, without requiring a secondary repository. The workflow is modified so that changes can be deployed per entity, rather than per document.

While a PR must still contain one document, the PR may involve any number of entities within the document. In theory, this could lead to difficult merge conflicts when multiple PRs target the same document. In practice, this may not be as bad as it seems.