Repository navigation
add CONTRIBUTING.md - #7255
add CONTRIBUTING.md#7255
Conversation
| @@ -0,0 +1,11 @@ | |||
| # Contributing to HTTPS Everywhere | |||
There was a problem hiding this comment.
Since this is only about contributions of rulesets, perhaps that should be reflected in the title/naming?
| @@ -0,0 +1,11 @@ | |||
| # Contributing to HTTPS Everywhere | |||
|
|
|||
| If you want to create new rules to submit to us, we expect them to be in the src/chrome/content/rules directory. That directory also contains a useful script, make-trivial-rule, to create a simple rule for a specified domain. There is also a script called trivial-validate.py, to check all the pending rules for several common errors and oversights. For example, if you wanted to make a rule for the example.com domain, you could run: | |||
There was a problem hiding this comment.
Style-wise, I would add some `'s to format the names of folders and files here.
There was a problem hiding this comment.
I would note that trivial-validate.py is located within the utils/ path just to be clear.
| cd src/chrome/content/rules | ||
| bash ./make-trivial-rule example.com | ||
| ``` | ||
| This would create Example.com.xml, which you could then take a look at and edit based on your knowledge of any specific URLs at example.com that do or don't work in HTTPS. Please have a look at our [Ruleset Style Guide](https://github.com/EFForg/https-everywhere/blob/master/ruleset-style.md) where you can find useful tips about finding more subdomains. Our goal is to have as many subdomains covered as we can find. |
There was a problem hiding this comment.
Our goal is to have as many subdomains covered as we can find.
As I've mentioned before, I generally applaud the thoroughness that goes into finding all of those, but it's time-consuming and I don't think that it should not be prioritized over work that creates greater value, so I would hesitate to add it as an explicit "goal", but I acknowledge that opinions on this may vary.
There was a problem hiding this comment.
Matching subdomains is almost the entire value of HTTPS Everywhere. Anyway what we want to discourage is new contributors submitting a basic rule for ^/www without trying, or even knowing that they should try, to dig a little deeper.
There was a problem hiding this comment.
In #6863 (comment) you gave an example where missing subdomains is "no big deal", so I would have thought you to be of a different opinion, but maybe I am misreading that, or something has changed since then.
There was a problem hiding this comment.
If we had literally zero domains in our ruleset collection, then HTTPS Everywhere would be useless even if all the rest of it was excellent. So, matching subdomains is really the whole point. Also I think you misread that comment, or I was unclear in it. That issue was about how exhaustively we should check for subdomains for institutional sites with dozens of obscure subdomains. Simple sites missing one or two subdomains are "no big deal", meaning not worth discussing, because in those cases (IMO) it is very easy to find them and ask the contributor to add them.
There was a problem hiding this comment.
That's also how I read the PR at hand, though: That the "goal" is exhaustiveness for individual rulesets, but we seem to agree that that's not necessarily the case.
There was a problem hiding this comment.
I think most people who read "Our goal is to have as many subdomains covered as we can find." will understand that as a suggestion that they need to do a little searching, not that they need to be super aggressive.
There was a problem hiding this comment.
I agree with @jeremyn here. I also think that having the CONTRIBUTING.md file err on the side of thoroughness is a good thing, because I expect that contributors tend to fall short of the level of exhaustiveness we'd prefer generally.* Having this language is probably a good thing so that the bar is a little higher, and it's better that contribs fall slightly short of a high bar than a low one.
- There's probably a number of reasons for this - either they're using automated scripts, or they are new to the project and aren't aware of our preferential procedure of subdomain inclusion.
| @@ -0,0 +1,11 @@ | |||
| # Contributing to HTTPS Everywhere | |||
|
|
|||
| If you want to create new rules to submit to us, we expect them to be in the src/chrome/content/rules directory. That directory also contains a useful script, make-trivial-rule, to create a simple rule for a specified domain. There is also a script called trivial-validate.py, to check all the pending rules for several common errors and oversights. For example, if you wanted to make a rule for the example.com domain, you could run: | |||
There was a problem hiding this comment.
I would note that trivial-validate.py is located within the utils/ path just to be clear.
| cd src/chrome/content/rules | ||
| bash ./make-trivial-rule example.com | ||
| ``` | ||
| This would create Example.com.xml, which you could then take a look at and edit based on your knowledge of any specific URLs at example.com that do or don't work in HTTPS. Please have a look at our [Ruleset Style Guide](https://github.com/EFForg/https-everywhere/blob/master/ruleset-style.md) where you can find useful tips about finding more subdomains. Our goal is to have as many subdomains covered as we can find. |
There was a problem hiding this comment.
I agree with @jeremyn here. I also think that having the CONTRIBUTING.md file err on the side of thoroughness is a good thing, because I expect that contributors tend to fall short of the level of exhaustiveness we'd prefer generally.* Having this language is probably a good thing so that the bar is a little higher, and it's better that contribs fall slightly short of a high bar than a low one.
- There's probably a number of reasons for this - either they're using automated scripts, or they are new to the project and aren't aware of our preferential procedure of subdomain inclusion.
|
I addressed most of the feedback, but I was not able to find a better language. I'm also not a native speaker. |
See also #6868
cc @jsha @Hainish @jeremyn @fuglede @cooperq