update source READMEs on modifying versions and pb bootfiles

racket/src/README.txt

@@ -451,6 +451,27 @@ When building BC for iOS, you may need to add `--disable-cify` for
 inheriting the build machine's disposition.
 
 
+========================================================================
+ Modifying Racket
+========================================================================
+
+See "cs/README.txt" and "bc/README.txt" for information about
+modifying those implementations of Racket, but one thing they have in
+common is updating the Racket version number. The source for the
+Racket version number is shared in "version/racket_version.h".
+
+The version number for the "base" package needs to be updated
+separately. If this directory is part of a clone of the Git repository
+for Racket, then the "base" version is in "../../pkgs/base/info.rkt".
+
+Unfortunately, there's no single source for the version number in both
+Racket and "base". Those are extracted as subtrees into separate
+distributions, and the point of a version in each place is to detect a
+mismatch between those extracted distributions. The "version.rktl"
+test in Racket's core test suite effectively checks that they're in
+sync within the Racket repo.
+
+
 ========================================================================
  Test Suite
 ========================================================================

racket/src/bc/README.txt

@@ -96,11 +96,11 @@ information.
  Modifying Racket
 ========================================================================
 
-If you modify Racket and change any primitive syntax or the collection
+If you modify Racket in a way that changes compiled code, including
-of built-in identifiers, be sure to update the version number in
+changing the set of primitives, be sure to update the version number
-"../version/racket_version.h", so that various tools know to rebuild
+in "../version/racket_version.h", so that various tools know to
-bytecode. If you add or remove primitives, you'll also need to adjust
+rebuild bytecode. If you add or remove primitives, you'll also need to
-the counter in "src/schminc.h" .
+adjust the counter in "src/schminc.h" .
 
 Some general guidelines for modying this code:
 

racket/src/cs/README.txt

@@ -536,3 +536,41 @@ conversion of a primitive reference to unsafe or not based on
 meant to expand to uses of unsafe operations should refer to the
 operations using `#3%`; beware that such a reference will stay unsafe,
 even if `UNSAFE_COMP` is disabled in the makefile.
+
+
+========================================================================
+ Modifying Racket
+========================================================================
+
+If you modify Racket in a way that changes compiled code, including
+changing the set of primitives, be sure to update the version number
+in "../version/racket_version.h", so that various tools know to
+rebuild bytecode.
+
+If you modify the Chez Scheme implementation in "../ChezScheme" in a
+way that changes compiled code, then you should also update the Chez
+Scheme version number in "../ChezScheme/s/cmacro.ss" and in
+"../ChezScheme/makefiles/Mf-install". For more about Chez Scheme's
+implementation and bootstrap, see "../ChezScheme/IMPLEMENTATION.md".
+
+If you're working in a checkout of the Racket Git repo, then when you
+update Chez Scheme in a way that needs new pb bootfiles, the updated
+bootfiles should be pushed to a new branch of the Racket pb repo and
+the Racket repo's top-level makefile should be updated to refer to the
+branch. Assuming that a working `racket` is in your path:
+
+ * Update ".makefile" in the checkout root to set `PB_BRANCH` to a
+   fresh branch name, typically based on the Racket version number.
+
+ * Use `make makemake` in the checkout root to build "Makefile" from
+   ".makefile" using `racket`.
+
+ * Use `make pb-build` in the checkout root to build pb bootfiles
+   using `racket`.
+
+ * Use `make pb-stage` in the checkout root to set up the new branch
+   locally. You could check that "../ChezScheme/boot/pb" looks
+   sensible at this point. The local branch checkout should have a
+   single commit in its history.
+
+ * Use `make pb-push` to push the new branch to the Racket pb repo.