Skip to content
This repository was archived by the owner on Nov 6, 2023. It is now read-only.

add CONTRIBUTING.md - #7255

Merged
Hainish merged 2 commits into
EFForg:masterfrom
J0WI:cont
Oct 24, 2016
Merged

Hainish merged 2 commits into
EFForg:masterfrom
J0WI:cont

Conversation

@J0WI

@J0WI J0WI commented Oct 1, 2016

Copy link
Copy Markdown
Contributor

@fuglede fuglede left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added my 25 øre.

Comment thread CONTRIBUTING.md Outdated
@@ -0,0 +1,11 @@
# Contributing to HTTPS Everywhere

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this is only about contributions of rulesets, perhaps that should be reflected in the title/naming?

Comment thread CONTRIBUTING.md Outdated
@@ -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:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Style-wise, I would add some `'s to format the names of folders and files here.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would note that trivial-validate.py is located within the utils/ path just to be clear.

Comment thread CONTRIBUTING.md Outdated
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@jeremyn jeremyn Oct 9, 2016 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@fuglede fuglede Oct 12, 2016 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@jeremyn jeremyn Oct 12, 2016 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread CONTRIBUTING.md Outdated
@@ -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:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would note that trivial-validate.py is located within the utils/ path just to be clear.

Comment thread CONTRIBUTING.md Outdated
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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@J0WI

J0WI commented Oct 22, 2016

Copy link
Copy Markdown
Contributor Author

I addressed most of the feedback, but I was not able to find a better language. I'm also not a native speaker.
My proposal is to add this file and maybe someone will improve it later or we will see, that more things need to be documented for new contributors.

@Hainish
Hainish merged commit 3d2f34f into EFForg:master Oct 24, 2016
@J0WI
J0WI deleted the cont branch October 24, 2016 22:51
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants