-
-
Notifications
You must be signed in to change notification settings - Fork 1.4k
Contributing: Proposals
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).
A proposal should be placed in the wiki for the Fyne project (presumably where you are viewing this document). The page title should begin with Proposal:
. The structure of the proposal may vary depending on the needs of the situation at hand, but you should generally try to include the following sections if they are relevant (keep in mind this is only a guideline):
- Introduction - describe briefly what you want to do and why.
- 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.
- Background - discuss any relevant background, such as links to articles, meeting minutes, issue or PR discussion threads, etc.
- 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, be sure to link it on the home page of the wiki!
Once you have written your proposal, you should post it in the #fyne-votes
slack channel. Include a link to the wiki page, 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 wiki page." -
:x:
- "I abstain from voting."
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 their approval of a specific option.
Discussion comments should be tracked in the wiki page for the proposal. Each new comment should use a ---
to separate it from the one above, and should include the name of the person making the comment.
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 proposal; 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 on the page, but moved into a "previous discussion" section.
- When a proposal is implemented, add the version it was added in to the top, and move it to the "Archive" section on the wiki home page.
- When issues or PRs relating to an open (un-archived) 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.
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.