Create a spec for composing proposals/specs

Phabricator Tickets
1

Information

ID: 668
PHID: PHID-TASK-vrojzkqrqodewof3rr4h
Author: dau
Status at Migration Time: open
Priority at Migration Time: Normal

Description

@Patrick and I had an idea to organize proposals/specifications to help the community propose, improve and follow some “ideas/standards”. The [[ GitHub - Kicksecure/proposals: https://phabricator.whonix.org/T635 | https://phabricator.whonix.org/T634 | 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/proposals

I 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?

Comments

Patrick

2017-05-01 01:03:55 UTC

dau

2017-05-01 17:17:44 UTC

Patrick

2017-05-01 18:49:32 UTC

dau

2017-05-02 23:09:00 UTC

Patrick

2017-05-03 11:28:55 UTC