Bringing the Annotator Toolkit to Apache

[Randall Leeds <ra...@apache.org>]

I'd like to consider migrating some of the libraries that make up the
"Annotator Toolkit", so to speak, into the Apache Annotator project. For
this, I am requested some help from our mentors, the permission of the rest
of the PPMC and the library authors, and feedback from the community on
this list.

Some of the libraries were mentioned in the initial project proposal [1]
while others have been developed since [2][3]. The primary authors of these
libraries are myself, Gerben (PPMC member, CC'd, @Treora on GitHub) and
Robert (CC'd, likely subscribed, @robertknight on GitHub).

This e-mail is broken into three parts:

1. Questions for Library Authors
2. Licensing Questions
3. Thoughts on Packaging

Questions for Library Authors

Gerben, would you be interested in bringing dom-highlight-range into the
project? We have an open issue [4] to build a highlighter. Benjamin and I
discussed at I Annotate that it would be immensely valuable for users to
have even a simple implementation. Your project is already a dependency of
the Apache Annotator demo, and its LICENSE [5] credits
dom-anchor-text-position.

Robert, would you be interested in bringing approx-string-match-js into the
project? The recent thread convinced me that there's a strong likelihood
that it could be leveraged by the selector framework that is starting to
take shape here.

For my part, I'm interested in bringing dom-node-iterator [6] and dom-seek
[7] into the project, both of which are now being used as dependencies.
These were both mentioned in the proposal [1], the latter under the name
"node-iterator-shim". I am the sole author of both of these.

Additionally, I may be interested in bringing dom-anchor-text-position [8]
into the project. It also contains an implementation of
Range.prototype.toString that I would like to be using.

Licensing Questions

For the mentors and anyone else familiar with Apache licensing
requirements, I would like to understand what steps are needed to import
code to an incubating project correctly.

For do-node-iterator and dom-seek, I am the sole author. It's possible I
could just commit this directly without any other process, but I would like
some advice first as to whether I need to formalize any copyright
assignment.

In the case of dom-highlight-range, Gerben is the sole author. Whatever
applies to the previous two libraries applies equally here, as Gerben is a
PPMC member.

For approx-string-match-js, Robert is the sole author. For
dom-anchor-text-position, I am the primary author and Robert has a
non-trivial contributions. The only other contribution was a small
correction to the README by Arun Prasad (https://github.com/akprasad).
Assuming Robert responds positively to bringing one or both of these
projects into Apache Annotator, I would like advise on what other steps we
would need to take to do that correctly.

Thoughts on Packaging

The repository is set up for bumping package version numbers in lockstep.
However, since all of these packages are published on npm, I probably want
to change the Lerna setup to make them independently versioned. It might
make sense to continue publishing some libraries under their original
names. We would still bundle and release these as part of
separately-versioned Apache Annotator releases, the first of which is a
topic I will raise in a separate thread shortly.

Regards,
Randall

[1]: https://cwiki.apache.org/confluence/display/ANNO/Annotator+Proposal
[2]: https://github.com/Treora/dom-highlight-range
[3]: https://github.com/robertknight/approx-string-match-js
[4]: https://github.com/apache/incubator-annotator/issues/22
[5]:
https://raw.githubusercontent.com/Treora/dom-highlight-range/master/LICENCE
[6]: https://github.com/tilgovi/dom-seek
[7]: https://github.com/tilgovi/dom-node-iterator
[8]: https://github.com/tilgovi/dom-anchor-text-position

Re: Bringing the Annotator Toolkit to Apache

[Robert Knight <ro...@hypothes.is>]

Hi Randall,

I’m happy for approx-string-match-js to be imported into the project if it helps other libraries in the project make use of it. As a general-purpose approximate string matching library it isn’t tied to the use case of annotation as much as the other libraries are though, and I’d like to retain the ability for interested parties to easily find / use it outside of that context. For that reason I think it would make sense for it to have a separate version number, where changes in the number reflect the semver impact on that particular library.

Kind Regards,
Rob.

> On 23 Jun 2019, at 01:15, Randall Leeds <ra...@apache.org> wrote:
> 
> I'd like to consider migrating some of the libraries that make up the "Annotator Toolkit", so to speak, into the Apache Annotator project. For this, I am requested some help from our mentors, the permission of the rest of the PPMC and the library authors, and feedback from the community on this list.
> 
> Some of the libraries were mentioned in the initial project proposal [1] while others have been developed since [2][3]. The primary authors of these libraries are myself, Gerben (PPMC member, CC'd, @Treora on GitHub) and Robert (CC'd, likely subscribed, @robertknight on GitHub).
> 
> This e-mail is broken into three parts:
> 
> 1. Questions for Library Authors
> 2. Licensing Questions
> 3. Thoughts on Packaging
> 
> Questions for Library Authors
> 
> Gerben, would you be interested in bringing dom-highlight-range into the project? We have an open issue [4] to build a highlighter. Benjamin and I discussed at I Annotate that it would be immensely valuable for users to have even a simple implementation. Your project is already a dependency of the Apache Annotator demo, and its LICENSE [5] credits dom-anchor-text-position.
> 
> Robert, would you be interested in bringing approx-string-match-js into the project? The recent thread convinced me that there's a strong likelihood that it could be leveraged by the selector framework that is starting to take shape here.
> 
> For my part, I'm interested in bringing dom-node-iterator [6] and dom-seek [7] into the project, both of which are now being used as dependencies. These were both mentioned in the proposal [1], the latter under the name "node-iterator-shim". I am the sole author of both of these.
> 
> Additionally, I may be interested in bringing dom-anchor-text-position [8] into the project. It also contains an implementation of Range.prototype.toString that I would like to be using.
> 
> Licensing Questions
> 
> For the mentors and anyone else familiar with Apache licensing requirements, I would like to understand what steps are needed to import code to an incubating project correctly.
> 
> For do-node-iterator and dom-seek, I am the sole author. It's possible I could just commit this directly without any other process, but I would like some advice first as to whether I need to formalize any copyright assignment.
> 
> In the case of dom-highlight-range, Gerben is the sole author. Whatever applies to the previous two libraries applies equally here, as Gerben is a PPMC member.
> 
> For approx-string-match-js, Robert is the sole author. For dom-anchor-text-position, I am the primary author and Robert has a non-trivial contributions. The only other contribution was a small correction to the README by Arun Prasad (https://github.com/akprasad <https://github.com/akprasad>). Assuming Robert responds positively to bringing one or both of these projects into Apache Annotator, I would like advise on what other steps we would need to take to do that correctly.
> 
> Thoughts on Packaging
> 
> The repository is set up for bumping package version numbers in lockstep. However, since all of these packages are published on npm, I probably want to change the Lerna setup to make them independently versioned. It might make sense to continue publishing some libraries under their original names. We would still bundle and release these as part of separately-versioned Apache Annotator releases, the first of which is a topic I will raise in a separate thread shortly.
> 
> Regards,
> Randall
> 
> [1]: https://cwiki.apache.org/confluence/display/ANNO/Annotator+Proposal <https://cwiki.apache.org/confluence/display/ANNO/Annotator+Proposal>
> [2]: https://github.com/Treora/dom-highlight-range <https://github.com/Treora/dom-highlight-range>
> [3]: https://github.com/robertknight/approx-string-match-js <https://github.com/robertknight/approx-string-match-js>
> [4]: https://github.com/apache/incubator-annotator/issues/22 <https://github.com/apache/incubator-annotator/issues/22>
> [5]: https://raw.githubusercontent.com/Treora/dom-highlight-range/master/LICENCE <https://raw.githubusercontent.com/Treora/dom-highlight-range/master/LICENCE>
> [6]: https://github.com/tilgovi/dom-seek <https://github.com/tilgovi/dom-seek>
> [7]: https://github.com/tilgovi/dom-node-iterator <https://github.com/tilgovi/dom-node-iterator>
> [8]: https://github.com/tilgovi/dom-anchor-text-position <https://github.com/tilgovi/dom-anchor-text-position>

Re: Bringing the Annotator Toolkit to Apache

[Gerben <ge...@treora.com.INVALID>]

I see I forgot to finish one line of thought mid-sentence.

As for the mentioned modules approx-string-match-js, dom-node-iterator,
dom-seek, dom-anchor-text-position; they all seem to fit in the project
scope, but feel a bit like an arbitrary collection of modules. Do you
have, or else shall we perhaps create, an overview of the modules we
want to create, and how they relate to each other? That way we would
have a clear reason why we have and maintain each module. In the
attached graph, I sketched the relations between the mentioned modules
(as I understand them), while already adding two hypothetical candidates
in grey.

— Gerben


On 6/27/19 2:53 PM, Gerben wrote:
> On 6/23/19 2:15 AM, Randall Leeds wrote:
>> […]
>>
>> Questions for Library Authors
>>
>> Gerben, would you be interested in bringing dom-highlight-range into
>> the project? We have an open issue [4] to build a highlighter.
>> Benjamin and I discussed at I Annotate that it would be immensely
>> valuable for users to have even a simple implementation. Your project
>> is already a dependency of the Apache Annotator demo, and its LICENSE
>> [5] credits dom-anchor-text-position.
> Sure, I’d be happy to group such modules under the Annotator umbrella. I
> agree it is valuable to have a highlighting tool available off-the-shelf
> (‘batteries included’), even if it may not be as generic/unopinionated
> as we would like other ‘core’ modules to be.
>
> I would not mind changing the name if that would be desired. Also both
> the API and implementation of the module could use some revision (I
> think this was my very first javascript module), but that could also
> happen after adopting it (e.g. use <mark> instead of <span>, make it an
> ES6 module, possibly return an object rather than just a cleanup
> function, …).
>
>> […]
> As for the mentioned modules approx-string-match-js, dom-node-iterator,
> dom-seek, dom-anchor-text-position;
>> Licensing Questions
>> […]
>> In the case of dom-highlight-range, Gerben is the sole author.
> A piece of it was copied from you (Randall). The rest I put out in the
> public domain, I hope that simplifies things.
>> […]
>
>

Re: Bringing the Annotator Toolkit to Apache

[Gerben <ge...@treora.com.INVALID>]

On 6/23/19 2:15 AM, Randall Leeds wrote:
> […]
>
> Questions for Library Authors
>
> Gerben, would you be interested in bringing dom-highlight-range into
> the project? We have an open issue [4] to build a highlighter.
> Benjamin and I discussed at I Annotate that it would be immensely
> valuable for users to have even a simple implementation. Your project
> is already a dependency of the Apache Annotator demo, and its LICENSE
> [5] credits dom-anchor-text-position.

Sure, I’d be happy to group such modules under the Annotator umbrella. I
agree it is valuable to have a highlighting tool available off-the-shelf
(‘batteries included’), even if it may not be as generic/unopinionated
as we would like other ‘core’ modules to be.

I would not mind changing the name if that would be desired. Also both
the API and implementation of the module could use some revision (I
think this was my very first javascript module), but that could also
happen after adopting it (e.g. use <mark> instead of <span>, make it an
ES6 module, possibly return an object rather than just a cleanup
function, …).

> […]
As for the mentioned modules approx-string-match-js, dom-node-iterator,
dom-seek, dom-anchor-text-position;
>
> Licensing Questions
> […]
> In the case of dom-highlight-range, Gerben is the sole author.
A piece of it was copied from you (Randall). The rest I put out in the
public domain, I hope that simplifies things.
> […]