This would probably be a little more convenient to work with in the client because we could then use the existing logic for turning API descriptions from the /api response into functions that make those calls.

The approach suggested here would be useful if the list of actions was dynamic but that's not the case as far as I am aware.

Is this purely a historical artefact or do they actually behave differently?

The client always uses uri, which is correct because the value is sometimes a urn:... URI (eg. for a PDF fingerprint). I'll also note that the client sets this parameter multiple times if it wants to query for annotations using multiple URIs (eg. on PDFs). This endpoint would need the same support in order to ensure that it retrieved flags for the same set of annotations.

The search endpoint allows us to fetch annotations for all groups at once and we use this in certain contexts - such as when opening a direct link where we don't know which group the annotation is in.

Could we drop the 'group' parameter here and make the call simply return the IDs of all flagged annotations, irrespective of group for the current URL?

The other reason this might be useful is it allows us to fetch flag info sooner because the client can make the request before it has fetched the list of groups.

I know why we do this but the practice of hiding the difference between 'not found' and 'wrong permissions' / 'incorrect' auth is really irritating from a debugging point of view. I'd like to us to reconsider this another time.

In the current designs the action is just a boolean flag, but I'll note that it is very common for reporting interfaces to allow the user to give a reason why they are reporting something. So I think it would make sense to design the API in such a way we can easily add that later if deemed useful.

Collection of official video tutorials for Hypothesis.

Video tutorial from Jun 2016 showing how to use Hypothesis to annotate a Wikipedia page.

It briefly shows groups and the stream, but using the old (pre-Nov 2016) Hypothesis website.

We've just discovered this doesn't work because the package version (in package.json) must be valid semver - which only allows for MAJOR.MINOR.PATCH and no further divisions. See discussion at https://hypothes-is.slack.com/archives/public/p1487778833005564

We worked around the issue thus far by bumping the minor version and making a note not to release a conflicting client version.

Twitter's mobile app is useful as a "production" example of what an application state tree can look like.

The temporary WebSocket URLs solve several problems. One is that they work around the fact that clients cannot supply Authorization headers directly using the browser's WebSocket API.

As a developer working on Hypothesis, this is useful to know. Is there anything you think we could do to make this easier?

The process of mapping quotes to DOM Ranges is referred to in the Hypothesis client as "anchoring". The code for anchoring quotes with fuzzy matching has been split out into a separate library with minimal dependencies - https://github.com/tilgovi/dom-anchor-text-quote

I presume "DOM tree" means "the logic which links annotations to the corresponding section of the page and renders highlights"? If so then we're currently discussing how to separate that out from the code which provides the sidebar.

If there is anything we can do to make the frontend (or parts of the frontend) of Hypothesis useful for Wikipedia projects, please let us know here or on the dev mailing list (https://groups.google.com/a/list.hypothes.is/forum/#!forum/dev )

A good summary of the value of automated deployment.

H - Happiness

E - Engagement

A - Adoption

R - Retention

T - Task success

More resources can be found on the site of the original paper's primary author: http://www.rodden.org/kerry/heart/

See https://www.reddit.com/r/learnprogramming/comments/25vdm8/what_is_a_prefork_worker_model_for_a_server/

I'm commenting here because the ticket is closed (and consequently locked), but we do have an accessibility report from August 2016 focused only on the client at https://docs.google.com/document/d/1aV4yOqR-rbBjy0t4z3cbmDfz4zKmJMt_YEXjYthGODQ/edit?ts=5745a68c

For Vim users, in addition to the plugin listed, there is also https://github.com/ElmCast/elm-vim , which provides autocompletion, integration with elm-format (for automatic formatting), elm-oracle (for code completion) and more.

Unlike Python 2, where a / b and a // b are both integer division by default. See http://stackoverflow.com/questions/14444520/two-forward-slashes-in-python

A useful guide on how to implement new Effect Managers. It was linked from elm-dev and presumably written for Elm 0.17.

I haven't checked how much of this is still applicable to Elm 0.18.

Description of a technique applicable to most (all?) modern browsers for achieving high performance animation of an element from an initial state to some destination state.

For a widespread example of this, see https://medium.com/node-security/the-most-common-xss-vulnerability-in-react-js-applications-2bdffbcc1fa0#.6c6dlwxgx

Footer - Chrome (3)

Footer (Chrome)

What does OG stand for here?

Image with Angular attribute directive.

Image tag with inline event handler

Script tag

Style tag

Image tag.

Italic text

Bold text

If my understanding of this is correct, a <form> with a missing "action" attribute should return the document URL when form.action is read. This does not appear to be the case in current versions of Chrome and Firefox, both of which return undefined.

When the "form" attribute is an empty string however, they do return the current document URL. Internet Explorer however returns the result of resolving an empty string against the document base URL (eg. if the page URL is /account/settings then form.action would return /account if the action attribute is present but empty).

This describes an interesting hack using iframes and document.write to enable incremental parsing and rendering of HTML loaded via an AJAX request.

In other words, null and undefined are assignable to every type. This was fixed in TypeScript 2.0 via the strictNullChecks option.

In other words, the Y axis values start at 0 at the bottom of the page and increase going upwards to the top of the page - the opposite of most familiar graphics systems.

This is a great, short guide for optimizing pull requests for review-ability.

We copied this approach for the Hypothesis web service by implementing a Jinja extension

Good beginners' introduction to the principles behind slow cooking.

"full whack" here means ~220° C for a fan oven.

Interesting dive into how string slicing with String#substring is implemented in the Dart and V8 VMs and the performance consequences of that. This investigation was prompted by poor performance of a port of less.js lexer to Dart vs. the original JS implementation.

The article ends with benchmarks showing the cost of trying to match sequences of characters in a lexer using a regex vs. manually.

Neat trick for matching regular expressions within a string starting at a fixed position using pre-ES6 features:

1. Create a regex with the global flag set which matches pattern|() where () is an irrefutable pattern which is guaranteed to match
2. Set regex.lastIndex to the position you want to match at
3. Use regex.exec(str)

Notes on how to match a regex starting at a given position in a string, making use of the sticky flag introduced in ES6.

The research paper described by this article can be found at http://kmunger.github.io/pdfs/Twitter_harassment_final.pdf

This was referenced by Google's Alex Russell no less when berating web developers for stuffing their apps/sites with too much JS and making users on slow networks/slower devices suffer from bad user experiences - https://twitter.com/slightlylate/status/799276604912377858

Vorlon.JS is a tool for remotely debugging JavaScript on any device. Use involves running a Vorlon debugging server on the machine hosting the web service and adding a script tag containing the client runtime to the page that you want to debug.

Any idea what happened here?

This is a criticism by Richard Feynman of maths textbooks that he reviewed while on the California State Curriculum Commission.

I came across it from from the Pedagogy section of the Wikipedia article on Feynman.

The complaints he makes are:

• That the books teach only very specific approaches to solving specific problems, which does not encourage the freedom of thought necessary for making use of maths in the real world.
• That the books unnecessarily phrase problems and explanations use the precise language of pure mathematics, when the problem could and should be stated in a way that laymen can understand
• That technical terms are introduced without actually explaining the associated concepts and facts.

https://www.ietf.org/rfc/rfc5077.txt

Lessons learned:

• The web platform provides a set of features which are useful for implementing modal overlays which appear above other content, trap focus etc.
• CSS outline properties can be used to create borders around elements that do not take up space but which do prevent clicks going through to elements underneath

A set of specs that allow mixins to be created natively in CSS. I learned about this from a talk by developers from Vaadin at the 2016 Polymer Summit

As utilization approaches 100%, the delay approaches infinity. Ignoring the Ts scaling factor the graph looks like this:

Possibly one of the motivations for the way queues leading to automated tills are arranged?

Useful introduction to regression testing for CSS.

Look ma, I'm annotating the stream!

Hello world.

In other languages:

• Python and Ruby: % is the modulus operator, same as mod in Haskell
• JavaScript, Rust, Go: % is a remainder operator, so same as rem

Summary of steps for making a Monad instance:

1. Understand conceptually what it would mean to put a value in a default context and to chain two operations in a particular context
2. For chaining operations, it can be helpful to take advantage of the law that m >>= f ≡ join (fmap f m) - in other words, the bind operator is the same as mapping the values in the monadic context over the function and then flattening the result
3. Define an instance Monad T typeclass instance which defines the return, >>= and (optionally) fail operations
4. Check that the monadic laws hold:
   1. return m >>= f ≡ f x
   2. m >>= return ≡ m
   3. f <=< (g <=< h) ≡ (f <=< g) <=< h

This is an annotation that has not been deleted

The broad proposal here, making replies distinct things from annotations so we can optimize based on how we want to store/query/retrieve them differently from annotations, sounds pretty sensible.

My suggestion for moving forwards would be to identify the restrictions that we might add (eg. replies must have the same access controls as their parent) and then introduce those artificially (eg. via UI changes in the client, validation in the API) as the first step. Then we can figure out if we're breaking anyone's workflow before we commit.

If by "work" you refer to number of API calls needed to get the relevant data, then yes - we want to make as few of those as possible.

If by "work" you mean computation or code complexity, then at least in our client, the code that takes the result from the API and builds a conversation thread is pretty simple. The JWZ code/algorithm that we used to use just made it seem complex.

Can you clarify this? I don't immediately see why we couldn't switch to the proposed design and support private replies on public annotations for example. It would require us to filter the conversation thread that is returned to the user, and if we don't really need that feature we shouldn't build it, but I don't obviously see it as severe obstacle.

What is the largest conversation we currently have in our DB, in terms of total number of characters and number of threads? My guess is that we could get away with imposing an arbitrary limit on the size of a conversation for now.

My personal view on this is that arbitrary levels of nesting are primarily a problem for a UI design perspective - because any piece of UX has to accommodate this, whereas designing for a fixed maximum depth would be easier.

Sheetal pointed out that Facebook (and I think at least one other platform) supported nested replies but only to a depth of two.

If we wanted to experiment with imposing a limit on the thread depth, without initially committing us it, is to change the thread building algorithm in the client, eg. behind a flag.

To check I understand the requirements here, you want to be able to index a conversation thread (annotation + all replies) as one ES document, and then in response to a query, return a data structure which contains the IDs of matching conversations plus the IDs of matching items (annotation or original reply) within those conversations?

So this is essentially the same problem as say, finding out which page matched if you were indexing multi-page documents?

Presumably ES can store position information with indexed terms. In that case here is one possible approach: Take all of the original items in the thread and serialize them into a single string - which is indexed with positional information, and separately the offsets of each item within that string are stored as a non-indexed field.

eg:

"content" field: annotation content | first reply | second reply
"offsets" field: <first reply ID>:<offset of first reply>,<second reply ID>:<offset of second reply>

When a search query is received, an ES query is performed to find the matching documents and get the offsets of matches within the "content" field. These offsets are then looked up in the "offsets" field to get the thread IDs.

Referenced by Rob Dodson in https://medium.com/@robdodson/the-case-for-custom-elements-part-1-65d807b4b439#.lo10wi144

Yes it is. IE >= 10 and up is the baseline. Since we are building the site in a way that we always have an HTML fallback, we can actually even build upgrades on a finer-grained basis - ie. have particular enhancements that don't apply unless a browser has certain features.

The Monad class now has a default implementation for return that uses pure, so the minimal definition is now just >>=

It looks like this has now been corrected - https://hackage.haskell.org/package/base-4.9.0.0/docs/src/GHC.Base.html#Monad

An annotation on the page

nb. fmap-ing a tuple applies the function to the second value of the pair because in order to make a 2-tuple the right kind to be used as a functor (* -> *), it has to be partially applied (ie. instance Functor ((,) x)) See http://stackoverflow.com/a/34604238/434243

What is the syntax that a derived Read parses when reading a list?

git blame is your friend :) - Nick's commit message in a2dce7780acd60480006a5c594eb8267ae09c5c4 has a detailed explanation.

This is done to force the use of a new TransactionManager instance for each request instead of using a thread-local instance.

According to http://docs.sqlalchemy.org/en/latest/orm/session_transaction.html , rollback() performs the same closure as commit(), which is what I would have expected.

If the client sends a query which excludes some annotations on the page, how will it then indicate how many other annotations there are to view? - As it currently does when you perform a local search.

There are two concerns here: 1) What data do we fetch from the server and 2) What subset of that data does the client initially show?

In the case where we direct-link to a single annotation for example, we fetch all annotations but only initially show the specified one, as opposed to fetching just the single annotation and then fetching more data if the user clicks 'Show all annotations'.

Is the query intended to be transparent to the client, in the sense that it can understand the query and parse out the annotation ID in order to set the selection? If so, this sounds sensible.

What about direct links to annotations on services other than Hypothesis? I think it would make sense for the hash fragment format to support that.

Some strawman ideas:

1. Add a service=<URL> parameter within the hypothesis query fragment. If omitted, this defaults to Hypothesis
2. Use JSON and encode an object like { serviceA : { query args }, serviceB : { query args } in the Hypothesis fragment. That seems too elaborate for the current requirements though.

I like this idea. I can see some potential caveats in future if/when we decide to add offline support or local caching of annotations - but we can revisit that when we come to it.

Several aspects of this article are out of date and do not reflect the final Shadow DOM v1 API. See https://developers.google.com/web/fundamentals/primers/shadowdom/ for a more up-to-date introduction

I think this meant to say "CSS styles defined outside the Shadow Root will not affect elements within the Shadow Root". In other words, styling in the containing document will not affect content within a Shadow DOM.

Hello google

What purposes is this used for other than login? Do we need to support the ability for Hypothesis users with 3rd-party accounts to login via our website. If not we could simply assume the default authority here.

Library (originally from Mozilla) for building components based on the W3C Web Components specs

A Web Component that can be used to pull fragments of HTML from the server and replace some placeholder content in the page once the fragment loads.

Framework for fast PE-navigation by updating just sections of a page that change during navigation, rather than reloading the whole page.

The purpose of rolling up/faceting is to help a user navigate a large number of search results by exposing different ways in which they can narrow their matches. It seems just as a relevant to me when presenting search results as when presenting activity.

We're grouping annotations by document rather than sorting. AFAIK and Conor can say more here, but the reason for this is that it was a key piece of feedback from some of our current users about how they want to browse results

How painful or pleasant paging through results is depends very much on how the "Show more" link works, how fast the results appear and how hard it is to go back and forwards.

I'm not sure I agree. The same issue arises in any search engine where you are looking for a particular thing but the query matches many other things and the output of the result sorting does not show the thing you are looking for on the first page.

The user's options are either to page through the results or to make the query more specific so that they match fewer annotations

The current proposed design searches annotations and groups by document. This is clear from the discussion. A risk is that if we get the interface design wrong, users won't realize this. If users aren't able to grok this, they are going to have a hard time using the interface.

An experimental performance comparison of client and server-side templating on desktop and mobile, focusing on time to first paint and time to last paint metrics.

The server is written in Go. The client is the simplest possible client-side templating you can do (using a <template> element and a few DOM API calls), so no frameworks involved.

Some takeaways:

• Everything on mobile is ~5x slower than desktop
• For small amounts of data, there is little difference in time to first paint
• Server-side rendering generates a modestly larger HTML payload vs. sending JSON down to the client
• Time to first paint is faster for SSR as the client can render markup as it is streaming down, but this is only significant when there is a decent amount of data on the page

Question - How is the server-rendering done and in what language?

I came across this from a post reflecting on the last Chrome summit.

The splash pages which appear to be basic static content with little interactivity load a 1.5MB JS bundle (500KB gzipped). Flipping back and forwards between pages feels sluggish in Firefox. My initial hypothesis is that letting the client's side router tear down the DOM for the current route and build up the DOM for the new route might be slower than just relying on the browser's back/forwards cache as a set of boring static pages would do.

Most of the solution here seems relatively unrelated to the actual goal of making managing splash pages across multiple locales easier.

Despite the misgivings I have about the way the whole site works, the styling code is simple and uses a pretty similar approach to what has been proposed for Hypothesis

Saw this recommended on a Quora answer whilst looking for book and article recommendations for a newcomer to Haskell

Link is broken, original paper is available at http://gallium.inria.fr/~naxu/research/escH-hw.pdf

This is a conclusion that follows from the earlier comment that errors are mistakes in the program, because a check was forgotten, whereas exceptions are anticipated failures that must be considered.

In the current version of Haskell, this example can be written as:

import Control.Exception
import System.Environment

main :: IO ()
main = toTry `catch` handler

toTry :: IO ()
toTry = do
  (fileName:_) <- getArgs
  contents <- readFile fileName
  print (length (lines contents))

handler :: IOError -> IO ()
handler _ = putStrLn "Failed to read file"

The catch function is deprecated and when I tried this with ghci 7.10.3 got an error that System.IO.Error does not export catch. The replacement is the catch function in Control.Exception

I initially did not see the difference in the output of B.cons vs B.cons' here, both output a plain string.

I think this is because of the Show typeclass implementation for Data.ByteString.Lazy which is used by ghci when printing values.

If on the other hand I use :force <expr> which fully evaluates <expr> and prints out the resulting structure then I do see the difference.

Broken link, should point to https://hackage.haskell.org/package/bytestring/docs/Data-ByteString-Lazy.html

Do we need to support older clients for more than a few days or can we simply drop support for real-time updates for any client released less than N days ago?

Slightly mad thought - could we serve the proxied page inside a sandbox iframe and get the browser to handle these security restrictions for us?

It looks like we will need to do this to handle SPAs at the moment or things like GitHub where some links are handled client-side. I started a discussion on the WICG group about adding an event that code could listen to in order to detect in-page URL changes.

By "links" you mean anchor tags? I think it is very useful to rewrite at least basic anchor tag links so that when annotating eg. a play spread over multiple pages, going from one section to the next at least stays "in Via".

Probably the best beginners introduction to what functional programming means "in the small" and why you would want to use this approach that I have read.

So in other words, writing code in a more functional style enables black-box testing.

Useful cheatsheat for Haskell operators

AFAIK compilers usually have specific optimizations to recognize and skip include guards.

Years later the Go language which Pike was hugely involved in mandated the use of capital letters for public struct fields and functions.

Annotation made on a copy from the first search result in Google Scholar

Maslow's hierarchy applied to user experience.

In short:

• Context
• Progression (getting from one step to the next)
• Devices
• Emotion (as in 'emotional state')

This is the section of the PDF specification that defines "file identifiers", comprised of two parts, the "permanent" file identifier which is generated when the PDF is first created and should not change on subsequent updates and the "update" identifier which may change when the PDF is modified.

The "permanent identifier" is what PDF.js refers to as the "document fingerprint".

runhaskell is an alias for the shorter runghc command and specifying the file extension is optional, so this can be shortened to:

runghc helloworld

I don't think this is accurate. The CSP needed to be modified at the very least in order to enable Genius' client-side code, that highlights annotations in the page and handles click events on them, to run. I assume they removed CSP entirely rather than restricting it because that was simply the technically easier thing to do.

I must be missing something. External scripts can access the location of the page they are loaded into via document.location.

JSCS has been merged into the ESLint project