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

2012-04-19 Thread Matthew Flatt
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.

_
  Racket Developers list:
  http://lists.racket-lang.org/dev


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

2012-04-18 Thread Danny Yoo
 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/zo-structs..rkt)._mod-srcname))


Is it guaranteed that if mod-name is a list, it's a list of at least
two symbols?



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?

Thank you!


---


Aside: it's times like these where I wish there was an extensive
Racket summary document similar to what Python does with their What's
New In Python XXX: http://docs.python.org/dev/whatsnew/.  I can read
git diffs, but I'd prefer to read documentation targeted for human
beings.  :)

The release highlights that are currently posted up per Racket release
are insufficient because they are too brief and because they primarily
serve a marketing role rather than a developer role.

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.
_
  Racket Developers list:
  http://lists.racket-lang.org/dev