@Patrick and I had an idea to organize proposals/specifications to help the community propose, improve and follow some "ideas/standards". The proposals repo is currently hosting these documents and we should write a spec to explain to other people how this works and how they can be composed.
Here is the initial draft I have in mind:
XXX Add a better introduction than the one above ^
# Quicksteps:
1. Create a ticket [2] describing the idea you have for a rule or
standard you think other people might find useful (if you already
have written a draft, add it to the ticket too)
2. Discuss with others and collect feedback
3. Once you have enough information to compose the document, create a text
file with the following headers:
# <Name of the proposal> (Proposal <Number assigned to the ticket you created>)
- Ticket: https://phabricator.whonix.org/T<Number>
- File: https://github.com/Whonix/proposals/blob/master/<Number>-<name-of-the-proposal>.txt
- Authors: XXX Should we use the usernames from Phabricator?
- [Supersedes:] <Number of the proposal/spec to be superseded, if applies>
- Status: Work in progress | Needs review | Accepted
<If needed, you may add other headers such as "Assignees",
"Priority", "Impact", etc>
4. Add a description section:
# Description
<Actual contents of the proposal>
<You may prefix certain parts of the document with "XXX" which is
unfinished or you need help with>
<Depending on the places you wish to share this document, you may
(or may not) use text formatting (e.g., markdown) and limit the
line length>
5. If needed, add a "TODO" section:
# TODO
<Tasks which still must be done>
6. Add the feedback paragraph and the references:
<References 0 and 1 are a bit redundant but are useful because we
remove the headers section at the top when posting to other
places that are not familiar to this workflow>
Feedback on the ticket [0] and pull requests on the repository [1]
are welcome.
[0]: https://phabricator.whonix.org/T<Number>
[1]: https://github.com/Whonix/proposals/blob/master/<Number>-<name-of-the-proposal>.txt
...
[N]: <Other references>
7. You may want to take a look at the proposals repo [3] for ideas on
how current proposals were written
8. Name this file in the format: `<Number>-<name-of-the-proposal>.txt`
9. Send a Pull Request (PR) with the file to the proposals repo [3] or
ask someone to do that for you if not familiar with git/GitHub
10. Update the ticket with the link once the PR is merged (you may
want to replace the draft in the ticket with the link so that you
do not have to update both places)
11. Feel free to continue discussing the proposal in the initial
ticket you opened and update the GitHub PR or create new ones to
improve it
[2]: https://phabricator.whonix.org/maniphest/task/edit/form/default/
[3]: https://github.com/Whonix/proposalsI noticed the Phabricator UI calls these "tasks". Do you call them tasks or tickets?
Do you think the "TODO" section should be at the end of the document or right after the headers?
What do you think?