~samwhited/xmpp

6962ae328de003ab725495986a4609e72b3dda6b — Sam Whited 1 year, 7 months ago 9b32216
design: create a formal proposal process

As I design more packages and features, I often find it helps to write
down what I think the solutions will be before actually implementing
them. Formalizing this process for others will give me a place to point
people if I have to ask them to write a design document.

Fixes #44

Signed-off-by: Sam Whited <sam@samwhited.com>
2 files changed, 101 insertions(+), 5 deletions(-)

M design/README.md
A design/template.md
M design/README.md => design/README.md +22 -5
@@ 1,6 1,23 @@
# Design Documents
# Proposals and Design Documents

This directory contains some design thoughts that I wanted to save while
designing this package. It is not meant to be a formal proposal process, but
feel free to submit patches adding new proposals using a similar format if
desired.
When working on a large change, you may be asked to first submit a design
document to make the change easier to understand and evaluate.
A template for proposals and design documents may be found in the file
[template.md].

The process involves:

1. Creating an issue at https://mellium.im/issue
2. A discussion on the issue tracker that may result in a request for a design
   document
3. The proposal author writes a design doc to work out any details and open
   issues and make the proposal more concrete
4. The design doc may go through several revisions and further discussion
5. The proposal is accepted or declined

Finally, if accepted, the proposal may be implemented and the patch set merged!

If you need help with this process, feel free to join the [chat
room](https://conversations.im/j/mellium@conference.samwhited.com).

[template.md]: https://mellium.im/design/template

A design/template.md => design/template.md +79 -0
@@ 0,0 1,79 @@
# Title

**Author(s):** Your name <email@example.net>  
**Last updated:** 2020-04-06  
**Status:** thinking|accepted|declined  
**Discussion:** https://mellium.im/issue/{issue number}

## Abstract

A sentence or two explaining *what* is being proposed.


## Terminology

This section includes any terminology that needs to be defined to understand the
rest of the document. This SHOULD include the latest text from [BCP 14]:

    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
    NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",
    "MAY", and "OPTIONAL" in this document are to be interpreted as
    described in BCP 14 [RFC2119] [RFC8174] when, and only when, they
    appear in all capitals, as shown here.

[BCP 14]: https://tools.ietf.org/html/bcp14


## Background

A longer description explaining what is being proposed in more detail, but also
why it is needed and the history of the issue or the feature in Mellium if
applicable, as well as any necessary background information required to fully
understand and evaluate the proposal 


## Requirements

- This will likely be a bulleted list
- Each requirement should be met by the proposal in the next section


## Proposal

The actual proposal.
This should include the entire public API and a summary of what this will mean
for compatibility and maintenance overhead going forward.
For example, it might include the various types, functions and methods in a
fenced code block.
This is a good place to go ahead and think about your documentation and how you
will explain to users what your types, methods, and functions do and how they
should use them.
For example:

```
// Cmd is an external command being prepared or run.
type Cmd struct {
	*exec.Cmd
}

	// New creates a new, unstarted, command.
	func New(ctx context.Context, name string, opts ...Option) (*Cmd, error)

	// Close kills the command if it is still running and cleans up any
	// temporary resources that were created.
	func (cmd *Cmd) Close() error

	// ConfigDir returns the temporary directory used to store config files.
	func (cmd *Cmd) ConfigDir() string

	// Dial attempts to connect to the server by dialing localhost and then
	// negotiating a stream with the location set to the domainpart of j and the
	// origin set to j.
	func (cmd *Cmd) Dial(ctx context.Context, j jid.JID, t *testing.T, features ...xmpp.StreamFeature) (*xmpp.Session, error)
```

## Open Issues

A list of known issues that still need to be addressed.
This section may be omitted if there are no open issues.