Page MenuHomePhabricator

Create a spec for composing proposals/specs
Open, NormalPublic

Description

@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/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?

Details

Impact
Normal

Event Timeline

dau created this task.Apr 30 2017, 10:42 PM
dau updated the task description. (Show Details)Apr 30 2017, 11:06 PM

XXX Should we use the usernames from Phabricator?

Probably not. But with higher priority, I'd leave that decision to the contributor.

  • Assignees: <Name of who is currently working in the proposal>

Not sure if useful but also not sure if it matters to leave/add/not add.

  • [Priority:] XXX How does Whonix currently handle this?

I use it to track time pressure. Such as hypothetic case: If a new version of Tor Browser that is going to be blessed stable in 2 weeks would not work in Whonix, then this would get the highest priority.

I don't use it for "this is more important than this".

  • [Impact:] XXX How does Whonix currently handle this?

Such as hypothetic case: If a new version of Tor Browser that is going to be blessed stable in 2 weeks would not work in Whonix, then the impact would be high.

Removing trailing spaces from source files has a low impact. Fixing a rare bug, normal impact. Adding a new anonymity protection feature, high impact.

Not too consistently used and not too important a field.

What gets assigned to the milestone of the next version of Whonix is not so much related on what's most important, but what's realistic and doable.

I don't think we need priority / impact on the proposal headers unless you find that useful. Changing priority / impact usually does not help to make someone else or me work on something sooner.

  • Status: Work in progress | Needs review | Accepted (XXX What else?)

Ok.

<(XXX Use markdown?)>

It's a case by case decision, maybe. Perhaps plain text works best most of the time. Markdown is okay if it's just for internal use at Whonix, but not great if we want to copy it over to third party (such as Debian) mailinglist or tracker that does not support markdown.

<(XXX Limit lines to 70 characters?)>

No hard line breaks. When to break lines should be up to browsers / mail clients / editors. But perhaps I am wrong about that.

Do you call them tasks or tickets?

Synonym, mostly tickets. Not sure about that.

Do you think the "TODO" section should be at the end of the document or right after the headers?

It's okay either way. I like to keep things simple and welcoming. With too strict rules about formalities, new contributors get discouraged for little to no gain.

What do you think?

Initial draft was very good already.

dau added a comment.May 1 2017, 7:17 PM

On Mon, May 01, 2017 at 01:03:57AM +0000, Patrick (Patrick Schleizer) wrote:

XXX Should we use the usernames from Phabricator?

Probably not. But with higher priority, I'd leave that decision to the contributor.

Alright.

  • Assignees: <Name of who is currently working in the proposal>

Not sure if useful but also not sure if it matters to leave/add/not add.

I am not sure either. May be useful if someone wants to talk to someone
about this? Maybe make it optional too?

  • [Priority:] XXX How does Whonix currently handle this?

I use it to track time pressure. Such as hypothetic case: If a new version of Tor Browser that is going to be blessed stable in 2 weeks would not work in Whonix, then this would get the highest priority.

I don't use it for "this is more important than this".

  • [Impact:] XXX How does Whonix currently handle this?

Such as hypothetic case: If a new version of Tor Browser that is going to be blessed stable in 2 weeks would not work in Whonix, then the impact would be high.

Removing trailing spaces from source files has a low impact. Fixing a rare bug, normal impact. Adding a new anonymity protection feature, high impact.

Not too consistently used and not too important a field.

What gets assigned to the milestone of the next version of Whonix is not so much related on what's most important, but what's realistic and doable.

I don't think we need priority / impact on the proposal headers unless you find that useful. Changing priority / impact usually does not help to make someone else or me work on something sooner.

Thanks for the explanation! Well, they might not indeed be useful
because we do not have a system like Phabricator/Maniphest to manage
them. So using them only on the tickets should be fine because then
we can filter/sort/etc, right?

<(XXX Use markdown?)>

It's a case by case decision, maybe. Perhaps plain text works best most of the time. Markdown is okay if it's just for internal use at Whonix, but not great if we want to copy it over to third party (such as Debian) mailinglist or tracker that does not support markdown.

I suggested markdown because it is reasonably popular and even if not
supported, its syntax does not impact the reading too much when
displayed as just plain text.

<(XXX Limit lines to 70 characters?)>

No hard line breaks. When to break lines should be up to browsers / mail clients / editors. But perhaps I am wrong about that.

The only reason I think that might be useful is when posting to
mailing lists because, personally, when reading mailman posts with
long lines (either on a browser or mail client) is not very
comfortable, but that is the experience I've had.

Do you call them tasks or tickets?

Synonym, mostly tickets. Not sure about that.

I think I will call them tickets too.

Do you think the "TODO" section should be at the end of the document or right after the headers?

It's okay either way. I like to keep things simple and welcoming. With too strict rules about formalities, new contributors get discouraged for little to no gain.

I agree! Maybe we should make all these suggestions instead of rules?

What do you think?

Initial draft was very good already.

Thanks!

dau (Felipe Dau):

dau added a comment.

dau updated the task description. (Show Details)May 3 2017, 1:07 AM

I just updated the text a bit with your feedback.

In T668#13170, @Patrick wrote:

dau (Felipe Dau):

dau added a comment.

Looks like your message got lost?

Looks like your message got lost?

Yes. Somehow...

dau (Felipe Dau):

dau added a comment.

On Mon, May 01, 2017 at 01:03:57AM +0000, Patrick (Patrick Schleizer)
wrote:

XXX Should we use the usernames from Phabricator?

Probably not. But with higher priority, I'd leave that decision to
the contributor.

Alright.

  • Assignees: <Name of who is currently working in the proposal>

Not sure if useful but also not sure if it matters to leave/add/not
add.

I am not sure either. May be useful if someone wants to talk to
someone about this? Maybe make it optional too?

Well, you have the git history and ticket discussion.

Yes, optional sounds good.

  • [Priority:] XXX How does Whonix currently handle this?

I use it to track time pressure. Such as hypothetic case: If a new
version of Tor Browser that is going to be blessed stable in 2
weeks would not work in Whonix, then this would get the highest
priority.

I don't use it for "this is more important than this".

  • [Impact:] XXX How does Whonix currently handle this?

Such as hypothetic case: If a new version of Tor Browser that is
going to be blessed stable in 2 weeks would not work in Whonix,
then the impact would be high.

Removing trailing spaces from source files has a low impact. Fixing
a rare bug, normal impact. Adding a new anonymity protection
feature, high impact.

Not too consistently used and not too important a field.

What gets assigned to the milestone of the next version of Whonix
is not so much related on what's most important, but what's
realistic and doable.

I don't think we need priority / impact on the proposal headers
unless you find that useful. Changing priority / impact usually
does not help to make someone else or me work on something sooner.

Thanks for the explanation! Well, they might not indeed be useful
because we do not have a system like Phabricator/Maniphest to manage
them. So using them only on the tickets should be fine because then
we can filter/sort/etc, right?

Right.

Do you think the "TODO" section should be at the end of the
document or right after the headers?

It's okay either way. I like to keep things simple and welcoming.
With too strict rules about formalities, new contributors get
discouraged for little to no gain.

I agree! Maybe we should make all these suggestions instead of
rules?

Yes.