[racket-dev] More low-level submodule questions, and changelog improvements?

At Wed, 18 Apr 2012 14:41:46 -0400, Danny Yoo wrote:
> >> I'm trying to wrap my head around submodules so I can get it working
> >> with Whalesong
> 
> 
> I see that the structure of 'mod' has changed a bit to accommodate
> submodules; in particular, mod-name can now be a list of symbols vs
> just a symbol, comparing:
> 
>     
> http://docs.racket-lang.org/raco/decompile.html#(def._((lib._compiler/zo-structs
> ..rkt)._mod-srcname))
> 
> vs:
> 
> http://pre.racket-lang.org/docs/html/raco/decompile.html#(def._((lib._compiler/z
> o-structs..rkt)._mod-srcname))
> 
> 
> Is it guaranteed that if mod-name is a list, it's a list of at least
> two symbols?

Yes. I see that contracts promise only a non-empty list, so I'll fix
that.

> I see the mod-pre-submodules and mod-post-submodules fields in the mod
> structure.  Those are the only changes I can see from:
> 
>     $ git diff v5.2.1 origin/release zo-structs.rkt
> 
> 
> I guess the runtime things I need to be careful about now are the
> changed semantics to resolved-module-paths.  Are there other changes I
> should pay particular attention to?

If you have a module name resolver or `load/use-compiled' handler,
the protocol for those changed slightly, too.

> Aside: it's times like these where I wish there was an extensive
> Racket summary document [...]
>
> In contrast, the document I'd like to see should be a guide that helps
> me migrate code.  It should document changes in the runtime behavior
> of core library functions, e.g. the change in what resolved module
> paths mean is implied by submodules.
> 
> I do remember that there used to be a Changelog document that
> described the changes per release, but I can't find it from the
> racket-lang.org web site.  From my memory, it didn't fulfill this
> migration role either.

The change log is

 doc/release-notes/racket/HISTORY.txt

and we try to keep it up-to-date with compatibility issues. I see that
it's missing the change to resolved module paths, though, which is a
serious omission that I'll fix.

You can get to the release notes from the documentation page by
following the "Release Notes" link on the left of the page, and then
the "Racket core" link.

The change log is not the more extensive prose description that you'd
prefer, though. At best, it's a list of alerts for updated
documentation that you should check. I would like to do better, but I
can't promise any more in the near future.