Https-everywhere: Release 2018.2.26 forthcoming

[Hainish]

Type: other

cc @jsha @pde @J0WI @diracdeltas @jeremyn @gloomy-ghost @brainwane @wonderchook

[Bisaloo]

It would really cool if you could use those issues to propose a tentative version of the release notes.

I find it very nice when softwares / extensions I use have detailed release notes. It gives users a sense of excitement at each release and helps them keep interest in the project (even when they don't directly contribute to it). On the contrary, projects with no/minimal release notes may give the impression that development has stalled (which is definitely not the case for HTTPS Everywhere!).

I feel like this is an area where HTTPS Everywhere could greatly improve with limited efforts.

For example, in this release:

• Many/most mixed content blocking issues are solved when using the "HTTPS only" mode thanks to the injection of the upgrade-insecure-requests header. This means "HTTPS only" can be more easily used for daily browsing with less site breakage.
• Rulesets are alphabetically sorted in HTTPS Everywhere popup.
• Many ruleset bugs have been solved (some dating 3 years back!)
• (Internal development scripts are now using python3.6 instead of python2.7)
• ...

[J0WI]

This could be automated with some Git magic.
Something like «git diff --shortstat --diff-filter=A 2018.1.29 src/chrome/content/rules/ | cut -f2 -d " " new rulesets have been added»?
(This is not accurate, but enhancements are welcome.)

[jeremyn]

I think there is not much value in putting detailed notes in these GitHub issues. We maintainers/frequent contributors are the only ones who read them. It would be more useful, and less trouble for @Hainish maybe, if an opt-in group were pinged on important issues and PRs. The opt-in people could then track the progress of these issues/PRs if they want.

General users don't know what HTTPS Everywhere does, or care, and so I doubt they would benefit much from release notes included in the UI, a popup tab, etc. I guess many think it is just "Block all unencrypted requests", or the EFF's take on Smart HTTPS.

If we are spitballing ideas to interest users, I'd like to see a sort of dashboard like what uBlock Origin has. I doubt most users understand that the real value of the add-on is the 20k+ rulesets. Even if the UI said something like (for example) "21,352 rules enabled, 3,241 disabled", that might help.

[jeremyn]

For some insight on what general users think, you can take a look at the add-on reviews for Firefox and Chrome.

[brainwane]

Release notes or a summary included in a CHANGES or CHANGELOG file are a common way to help new contributors and technically skilled users understand the project at a more conceptual level, rather than just making them read all the commit messages. For more on this, please see Karl Fogel's book _Producing Open Source Software_, especially the section on packaging in Chapter 7 and the section on announcing new releases.

People who are new to a codebase need is to know the design rationale of the codebase and changes to it -- why it was made this way, what decisions are embedded in particular choices, whether particular components are the result of a feature request, a quick fix after an outage, an experiment, a step towards a larger goal on the roadmap, etc. Release notes are a form of documentation that newer contributors find easier to understand, as release notes provide information in a structure closer to a newcomer's mental model. (This is based on research summarized in Making Software.) Fogel also points out the value of treating every user as a potential new participant.

To sum up, I agree with @Bisaloo and @J0WI here.

[brainwane]

And I further agree with @gloomy-ghost and @cschanaj who thumbs-upped @Bisaloo's comment.

[Bisaloo]

I think there is not much value in putting detailed notes in these GitHub issues. We maintainers/frequent contributors are the only ones who read them. It would be more useful, and less trouble for @Hainish maybe, if an opt-in group were pinged on important issues and PRs. The opt-in people could then track the progress of these issues/PRs if they want.

I think we are not talking about the same thing.

I was talking about making a draft for release notes in these GitHub issues. They would then be included in the release and added to the Firefox about:addons UI (see screenshot for an example).

This is totally opt-in and non-invasive. Users have to click Show release notes to display them. Non-technical users that don't even visit about:addons will never know about this.

I think it's a mistake to assume that only HTTPS Everywhere contributors/maintainers will read them. I have never contributed to extensions such as uBlock Origin, uMatrix, and many others. Yet I still read the release notes for every single release.

By the way, since you started talking about other extensions such as uBlock Origin, you can notice that many extensions have way more detailed release notes than HTTPS Everywhere. Example: uBlock Origin, uMatrix, Stylus. Granted HTTPS Everywhere is slightly different from other extension because users don't care about most ruleset changes (although some of them might be of interest, for example when amazon switched to HTTPS) but there is still room for improvement IMHO.

[jeremyn]

If someone wants to make nice release notes, that's fine. I don't think they are needed in these GitHub issues.

HTTPS Everywhere volunteer outreach has a lot of room for improvement. I wouldn't focus on release notes as a first step, but if someone wants to take it on, go for it, as far as I'm concerned.

[Hainish]

@Bisaloo

It would really cool if you could use those issues to propose a tentative version of the release notes.

I'm reluctant to create detailed release notes when initially creating the issue for two reasons:

1. Often, the issue is created right after the previous release is made, in order to schedule it out ahead of time. At that point, there's nothing to add.
2. I want to lower the cost of creating issues like this. I'm less likely to announce a forthcoming release if there's a lot of associated up-front cost.

In order to choose what to include in the Changelog, I'll often run the command:

git log -- . ":(exclude)src/chrome/content/rules"

and simply look back on the commit history to see what has changed since the last release. I'll always include the Ruleset updates line in https://github.com/EFForg/https-everywhere/blob/master/src/Changelog, since there are pretty much always updates to that and, as @Bisaloo points out,

HTTPS Everywhere is slightly different from other extension because users don't care about most ruleset changes (although some of them might be of interest, for example when amazon switched to HTTPS) but there is still room for improvement IMHO.

I will occasionally mention specific ruleset changes, such as https://github.com/EFForg/https-everywhere/blob/b8b48b4346caf12ac605484274287631d6a8cfe2/src/Changelog#L142

I also exclude changes to the tests and tooling, since this is unrelated to the actual software being released to users. For instance, I'd exclude the above

• (Internal development scripts are now using python3.6 instead of python2.7)

I'm happy to include the most relevant details in the Changelog, and provide more comprehensive release notes in the extension store and when announcing to the HTTPS Everywhere list. This does require additional effort and budgeting more time to do the release, though. Releases take long enough to get out the door as it is, I'd like to lower that overhead rather than heighten it. If we could decentralize some of that burden via issues such as this, I'm open to it.

[Hainish]

At any rate this discussion belongs in a separate issue, since I close these once the release has been made.

[J0WI]

981 might be a good place to start

[jeremyn]

Also issue https://github.com/EFForg/https-everywhere/issues/13716 "Add release notes to EFF hosted version".

[Hainish]

@Bisaloo thanks for providing the summary, I'm going to lift this in part for the Changelog for this release.

[Hainish]

Release made!