Spec change notification

[seshrs]

As a student, I remember being extremely annoyed about how specs could change in the middle of a project. Many times, changelogs weren't posted on the spec itself, and were only posted on Piazza (where notes tend to be lost in the noise).

It would be nice if Primer Spec could determine if the page's content has changed since the last time the browser viewed the page. When a change is detected, maybe add some alert in the Topbar (next to the Settings icon), and provide an option to view changes since the last page visit.

I'm not entirely sure about the best way to implement this. Here are my current thoughts:

• Store the page content in local storage. (Need to test performance with large strings similar to an actual EECS project.)
• When the page loads, compare the content string with the locally stored string to determine if content has changed.
• If content has changed, alert the user. Perhaps add an "Alert" icon to the Topbar.
• Offer option to display changes. This would display a side-by-side or inline HTML diff view. This is probably the trickiest aspect of this feature. Perhaps we could take inspiration from: https://github.com/adamarthurryan/dubdiff
• Offer users the option to disable spec-change notifications in the Settings.

[awdeorio]

This is very tricky! The "easiest" way to implement something like this would be to add Git as a dependency (ugh).

A few problems that could pop up.

• What if I view the spec, then the spec changes, then I clear my cookies and cache, then I view the spec again?
• What if I view the spec, then the spec changes, then I view the spec with a different web browser?
• What if I view the spec, then the spec changes, then I view the spec with private browsing mode?
• What if there's an important change to the spec and I want to view that diff at a later time? Is there a permalink?
• What if there are several changes, is there a way to view the history of changes?
• What if something trivial changes, like a spelling error?
• What if I'm in, say EECS 280, and I have no idea what HTML is. Will I have to understand an HTML diff?
• HTML content (the English part) is often very long lines. Will the UI make it clear what words changed in a very long line?

One possible alternative would be to automatically generate some sort of changelog. This could be viewed as a separate web page and link to the relevant new parts of the spec.

Another possible alternative would be to simply detect the last modified date. Then, put a big fat warning at the top if it changes saying "contact the course staff" or something like that. If profs are changing the spec in the middle of a project and they don't add a changelog to the top of the spec, they deserve to be chastised with many emails.

[seshrs]

Thanks for your detailed notes and questions @awdeorio! I really appreciate it 😃

Clearly I need to think through what this would look like for students a bit more. I’ll explain my rationale a bit further, and we can determine if such a feature still makes sense.

---

This feature shouldn’t replace manually-written changelogs. (If a project is changed in the middle of a semester, the best way for staff to communicate the nature of the changes is via a changelog.)

However, even if a changelog is maintained, students may not realize that the spec has changed if they aren’t looking at the changelog. This has happened to me a few times as a student 😅

You’re right that there are a bunch of problematic cases. IMO I think false negatives are fine (since it would behave just like it does today). But if we happen to detect a change, it might be nice to let students know to check the changes.

I like the idea of a floating warning banner at the top of the page :)

What if there's an important change to the spec and I want to view that diff at a later time? Is there a permalink?

What if there are several changes, is there a way to view the history of changes?

I think showing the warning banner once per change is sufficient. I don’t want to replace the need for changelogs, and permalinks might add a lot of complexity 😅

What if something trivial changes, like a spelling error?

Great question! My guess is that it doesn’t hurt for students to see what typos have been fixed...? At the same time, I wonder if students would panic if they saw warning banners when the changes are minor. I’d hope that students would view the diff to be sure...

What if I'm in, say EECS 280, and I have no idea what HTML is. Will I have to understand an HTML diff?

HTML content (the English part) is often very long lines. Will the UI make it clear what words changed in a very long line?

I was thinking of generating a rich diff preview like GitHub does for Markdown files. Something like this. We can tweak the diffing algorithm to work with longer lines better.

One possible alternative would be to automatically generate some sort of changelog. This could be viewed as a separate web page and link to the relevant new parts of the spec.

This might be possible, maybe clicking the warning banner opens a new tab with this rich diff. I’m not entirely sure how it would work with Jekyll sites though, I’ll have to investigate...

Another possible alternative would be to simply detect the last modified date.

Unfortunately, I don’t think this is possible. 😞 The Jekyll theme only has access to the time at which the entire site is regenerated. This doesn’t indicate if a page has changed since the student last visited — in fact, every commit to master regenerates the site — so we’d end up with a bunch of false positives.