organizing the lists

[myrdd]

I'd like to organize the lists with comments.
I tried to add comment to a json file (see here) before I figured out that comments are not allowed or rather specified for json files. To organize the subscriptions it would be good to be able to add comments. A solution would be to have a file with comments and an automatic tool would remove the comments / convert to json.

[nodiscc]

I think trying to classify rules with comments will quickly become unmanageable. What I suggest:

• Review allow_sameorg.json (Review allow_sameorg.json #10) by visiting each site, adding strictly necessary rules to a temporary file (say review.json), and add the rule description in the git commit message. When done, rename this file to allow_sameorg.json
• If users wants to review the purpose of a particular rule, it can be done using git blame, or the "blame" feature on github. The current sameorg file has no git history.
• It allows sorting the file alphabetically.
• A general description of the json file can be added to the README

[myrdd]

Review allow_sameorg.json (#10) by visiting each site, adding strictly necessary rules to a temporary file (say review.json), and add the rule description in the git commit message. When done, rename this file to allow_sameorg.json

What we should do is written in #9 (comment)

If users wants to review the purpose of a particular rule, it can be done using git blame, or the "blame" feature on github. The current sameorg file has no git history.

Quite inconvenient… Also, this way "comments" can't be changed without changing the line itself.

Remark: AFAICT github (currently) does not use the --follow option when creating the blame page – example

It allows sorting the file alphabetically.

Why would you sort them alphabetically?
E.g. youtube makes requests to ytimg.com, so if you have a rule to youXYZ.com it will be like

youtube.com
youXYZ.com
ytimg.com

Are there any advantages of sorting over grouping?
If sorting is important, we could manage rules/subscriptions in a separate file and have a "build" script which creates a json and orders the entries. This would even allow comments (which I would like to have).

A general description of the json file can be added to the README

IMHO we should extend the format of the subscription list file, currently official.json. Currently the format is like this:

{
  "subscriptions":{
    "allow_embedded":{
      "serial":1329159661,
      "url":"https://…/subscriptions/master/official-allow_embedded.json"
    }
  }
}

and I propose something like the following:

{
  "l10n": "https://…/subscriptions/master/locale/**language-code**.json",
  "region-specific": "https://…/subscriptions/master/regions/**region-or-country**/official.json",
  "subscriptions":{
    "allow_embedded":{
      "serial":1329159661,
      "url":"https://…/subscriptions/master/official-allow_embedded.json",
      "title": "My title goes here",
      "description": "Description of allow_embedded…"
    }
  }
}

The l10n folder will contain locaization strings.
The region-specific directories will contain subscriptions specifically interesting for france.
The entries title and description will be english and translated in l10n.

Having the description in the json file makes the subscription system independent from the source code. Currently the list is hard-coded. Also this would make RP ready for unofficial subscriptions – it would be optional though.

Btw, we might have to create new issues for what I've been proposing.

[nodiscc]

Why would you sort them alphabetically?

@myrdd Because it makes it a lot easier to find if a rule already exists when adding new rules to a subscription. It keeps the diffs to a minimum, makes it easier to detect duplicate rules, and prevents searching the whole list by eye for a particular rule. Contributors can just add new items, sort the list and commit.

(See also #6 and #11)

[myrdd]

So you are not in favour of "building" the subscriptions file? Note that it could be possible to have both alphabetically sorted and thematically grouped subscriptions concurrently.

So in other words, I suggest to find a method to manage rules alphabetically and grouped at the same time. (Personally I prefer grouped rules)
– on the other hand it's you who mainly manages subscriptions (at least atm), so take it like a suggestion. :)

[nodiscc]

Personally I prefer grouped rules

After doing some work on the subscriptions, I think you're right. It's easier to read the subscription if rules are grouped in logical/browsing order.

(it can be done using git blame) Quite inconvenient

Yes.

The entries title and description will be english and translated in l10n.

Yes we should add those fields. Can you report an issue for this (as you have a better picture in mind than I do)? Then this one can be closed.

[myrdd]

Can you report an issue for this

I've created issue RequestPolicyContinued/requestpolicy#550

[nodiscc]

Moved to #29 and #21