Contributing: Proposals

Purpose

If you want to propose a new feature, API, architectural change, etc. then you should follow this document. A proposal document should describe the changes you intend to make, and will also serve to document any discussion about said changes. You only need to write a proposal if you are making a large, far-reaching, and/or breaking change that has not been previously discussed and documented (e.g. if there is already an open issue to implement a feature, a proposal is not needed unless you wish to have a discussion, or want a space to plan out your changes).

Unlike a code PR or an issue, a proposal is not an immediate action item. You can use a proposal as a place to sketch out an idea you had, get feedback, etc. without jumping to the implementation right away. This makes proposals a great place for aspirational ideas that cannot be implemented in the immediate short-term, but where we still want to plan and discuss in advance.

Writing A Proposal

Proposals are collected in the proposal repository. The contents of the proposal may vary depending on the needs of the situation at hand, but you should generally start by copying the template and filling it in. The following hints may help to consider what to include.

• Introduction - describe briefly what you want to do and why.
• Background - discuss any relevant background, such as links to articles, meeting minutes, issue or PR discussion threads, etc.
• Architecture - discuss any architectural changes in detail, including sketches of APIs, proposed types and interfaces, etc.
• Design - discuss any design changes or considerations in detail, including wireframes, sketches, mock-ups, etc.
• Implementation - discuss any implementation details, such as how interfacing with specific hardware, OSes, external APIs, etc. might be handled.
• Prior Art - if some other toolkit, API, language, library, etc. has done the same thing as you are proposing, post a link to any documentation or code you can find, and try to dig in and briefly discuss anything relevant in this section. This is a great place to evaluate stumbling blocks that we can avoid with the benefit of hindsight.

Once your proposal is written, open a pull request on the proposal repository and send a link to the #fyne-contributors channel on gophers Slack server.

Discussing A Proposal

Once you have written your proposal, you should post it in the #fyne-contributors slack channel. Include a link to the pull request, and a brief (1-3 sentences) description of it. People will react with one of the following emojis:

• :thumbsup: - "I support this proposal as-is."
• :thumbsdown: - "I do not support this proposal even with changes."
• :eyes: - "I have seen this proposal, but want to discuss before approving - see my comments in the PR."

Additionally, in the event you wish to propose multiple different approaches or options, you may at your discretion number them, and have people react using :one:, :two:, etc. to indicate a preference for specific options.

Comments on the proposal will be tracked like any other PR. You can make suggestions or change requests and the document will evolve over time according to feedback.

Maintaining A Proposal

The needs of each situation will vary, so use your discretion, but here are some guidelines to maintain a proposal throughout it's lifecycle:

• New discussion comments should be added at the end of the PR; old comments should not be edited or modified (except minor spelling/grammar fixes by their author).
• If the discussion strays too far from the working state of the proposal, consider re-writing an updated proposal, keeping the existing content, but moved into a "previous discussion" section.
• When a proposal is implemented, add the version it was added in to the top, and merge the pull request.
• When issues or PRs relate to an open proposal, add links to them at the top.
• If you discuss the proposal in a meeting, Slack, email, etc. then you should add a note summarizing the discussion, just like the discussion comments noted before.
• When a consensus has been reached and the team has agreed to a proposal, you should open an issue and/or PR as appropriate in the Fyne repository, linking back to the proposal.
  • Implementation details, comments, questions related to a specific issue or PR belong in the discussion for that PR, while higher-level, more abstract discussions should be tracked in the proposal.

Rationale

This style ensures that:

• The discussion about a particular proposal is kept in one, central place.
• The discussion is archived for posterity so it can be referenced later.
• Because the discussion is asynchronous (e.g. not in Slack), people who can only sign on infrequently or are in different time zones can also weigh in.