report from December leadership meeting

[Matthew Flatt]

Every few months, the principals of the Racket world meet for a day to
discuss the state and near (and, occasionally, distant) future of the
Racket world. We met on the weekend of December 5 in Dunstable, MA,
and here is the list of major points we discussed.

1. Contributions and Software Freedom Conservancy

Our application to the Software Freedom Conservancy, which would
help us to accept tax-deductible contributions, is still pending.
Meanwhile, we will prepare PLT Design Inc. to accept income, so
that we can also support other means of (non-tax-deductible)
contributions and to manage RacketCon.

2. Package maintainers

When package creators become unable to continue as maintainers,
sometimes a package name needs to be reallocated to a repository
where a new maintainer has control. In his role as the curator at
pkgs.racket-lang.org, Jay has been reallocating package names as
necessary, but we'd like to make the process more transparent. Jay
will start announcing these transitions on the dev list. Longer
term, pkgs.racket-lang.org should provide an interface for these
announcements, discussion, and history.

We'd also like to build up a better culture and tool support for
documenting a library's internals. We need to discuss this more, but
we have one idea for now: code walk-throughs in the form of video
recordings. Jay will recruit presenters and arrange recordings.

3. Backwards compatibility and adding library exports

Although our general policy on package updates is that they should
be backward-compatible, we make a significant exception for the
case of adding exports to an existing library. Adding an export
mostly works out, but it's not backward-compatible, because it can
create conflicts in existing code.

Recent technical changes have lessened the effect of conflicts, and
we can take one more technical step: make import conflicts an error
only if the conflicting identifier is actually used. Matthew will
try that change.

At the same time, we'd like to refine the policy on adding exports:
it's ok to add a new export as long as it doesn't create a conflict
for any code that is registered on pkgs.racket-lang.org. To support
this policy, Robby will set up snapshot-based package build, which
will complement the release-based package build at
pkg-build.racket-lang.org, and Jay will update pkgs.racket-lang.org
to have a new column that shows results with the snapshot.

4. Release-time testing

Our release testing process seems to have gotten slower as
release-time testers struggle to find time for their checklist
items. Also, the process of posting the checklist and responses to
the dev list is not working well for people who try to keep track
of the release state.

To address the latter problem, we're moving the checklist to a wiki
page. To help with the former problem, we're expanding the
checklist to contain more information about how each check is
performed, so that others who have time around a given release will
be able to help check off items.

A related issue is that examples in the documentation sometimes
fail in a way that indicates a bug. By having that failure be a
documentation-build failure, instead of rendered as an error
message in the documentation, we can avoid some errors in a
release. Matthew will add a replacement for `examples` where forms
that are intended to be rendered as errors must be explicitly
marked as such, while other errors trigger a document failure.

5. docs.racket-lang.org

Currently, docs.racket-lang.org shows only documentation that's
included in the distribution for the most recent release. The plan
has always been to push documentation for package builds there, so
that documentation for all packages is searchable in a single place.
Matthew will make that switch soon.

[Alexis King]

> A related issue is that examples in the documentation sometimes
> fail in a way that indicates a bug. By having that failure be a
> documentation-build failure, instead of rendered as an error
> message in the documentation, we can avoid some errors in a
> release. Matthew will add a replacement for `examples` where forms
> that are intended to be rendered as errors must be explicitly
> marked as such, while other errors trigger a document failure.

This, along with a fixed eval:check, is a wonderful change. Documentation examples that also serve as an ad-hoc test suite is a pretty cool idea. I’m very excited to be able to use these.

There is a problem, though: I can’t use them without dropping support for older Racket versions because these are entirely new forms. This was something I was thinking about lately: having monolithic “releases” makes it impossible to backport changes to older Racket versions. For example, the new scribble/example(s) module seems like something that would work with lots of Racket versions were it a package, but since it’s part of the core, scribble-lib will be locked to older versions on old releases.

Am I wrong about this? Maybe it would work if I explicitly depend on a newer scribble-lib version? I think I’m a little unclear about that.

Anyway, that’s a tangent. These all seem like good decisions, and I’m interested to see them be applied.

Alexis

[Matthew Flatt]

Although the current "scribble-lib" does install in v6.3 (using `raco
pkg update --catalog http://pkgs.racket-lang.org scribble-lib`), you
probably don't want to create a package that can only be used in older
versions by first upgrading a main-distribution package.

One alternative is to create a "scribble-example-lib" package and
register it at pkgs.racket-lang.org with different implementations for
different Racket versions: as a copy of `scribble/example` for version
6.3 and earlier, and as a package that just implies "scribble-lib" for
post-6.3 versions.

As another alternative, we could move `scribble/example` out of
"scribble-lib" and into a "scribble-example-lib" package (and either
make "scribble-lib" imply the new package or adjust our handful of uses
to depend on "scribble-example-lib"). Then, your package could require
"scribble-example-lib", and we could make sure that
"scribble-example-lib" works in older versions of Racket.


The second alternative requires a little extra work. The
`scribble/example` library is currently implemented in terms of an
improved `scribble/eval`. So, the implementation has to be shuffled a
little to put the new `scribble/eval` as some private library in
"scribble-example-lib", and then `scribble/eval` in the new
"scribble-lib" can re-export that other library (while `scribble/eval`
for previous releases remains unimproved).

Of course, "scribble-example-lib" would become a part of the main
distribution in the next release, the same as "scribble-lib", since
main-distribution documentation will rely on it. If `scribble/example`
needs to be improved later, then we run into all the same problems
again. Also, we'll have to deal with the extra "scribble-example-lib"
layer forever.


I lean toward the first alternative, since it means
"scribble-example-lib" will mostly move out of the way after the next
release. I don't have a strong objection to the second alternative,
though.

[Vincent St-Amour]

FWIW, the first option also sounds better to me.

Vincent

[Matthew Butterick]

I use Racket as a business tool, thus I have treated payments to PLT as business expenses (and thus tax deductible for that reason). The nonprofit angle doesn't inhibit me.

What does inhibit me, stupidly enough, is some kind of approved method for transferring money. Let me try to put an end to that:

If you told me an email address that I could use as a target of electronic payments (PayPal? Venmo? What would be best?) then I would set up a recurring payment of $100 a month as a payment for the many Racket services I consume (e.g., pkg-build, which I believe is down right now, but I consider that my fault).

[Matthew Flatt]

At Mon, 4 Jan 2016 08:34:02 -0800 (PST), Matthew Butterick wrote:
> pkg-build, which I believe is down right now

We're switching DNS providers today, and I get that entry wrong. I
think I've fixed it, so you should see the site as the latest DNS
updates reach your network.

[Matthew Butterick]

Thanks Matthew. I see it now.

Perhaps related, but probably not: links to text files that work in a local installation, do not work on pkg-build (I'm supposing due to an htaccess restriction)

For instance, this:

http://pkg-build.racket-lang.org/home/racket/build-pkgs/user/.racket/6.3/pkgs/aoc-racket/day2-input.txt

Should get you this:

https://raw.githubusercontent.com/mbutterick/aoc-racket/master/day2-input.txt

[Matthew Flatt]

At Mon, 4 Jan 2016 10:11:01 -0800 (PST), Matthew Butterick wrote:
> Perhaps related, but probably not: links to text files that work in a local
> installation, do not work on pkg-build (I'm supposing due to an htaccess
> restriction)
>
> For instance, this:
>
> http://pkg-build.racket-lang.org/home/racket/build-pkgs/user/.racket/6.3/pkgs/a
> oc-racket/day2-input.txt
>
> Should get you this:
>
> https://raw.githubusercontent.com/mbutterick/aoc-racket/master/day2-input.txt

The problem is that the package is built in a different place than
where the package is installed, and so the text file doesn't get
carried along with the documentation. (That is, you've used
`define-runtime-path` to refer to the file at its run-time location for
the document, but the run time of a document is not the same as the
time when a document is read by a human, and the locations of those two
times can be different.)

Instead of using `link` with the document-run-time path, use a
`link-resource` property:

(require scribble/html-properties
scribble/core)

(define (link-rp path . text-args)
(element (style #f (list (link-resource path)))
text-args))

As a simplification, this `link-rp` takes a relative path. That works
(instead of using `define-runtime-path`) because documentation is
always rendered with its enclosing documentation as the relative path.

Probably, something like `link-rp` belongs in `scribble/base`, since
`link-resource` is difficult to find and use.