Update READMEs: Pmodules wiki background, unx-mx_adm permissions, build-* propagation notes

- main README: add Pmodules background from wiki, unx-mx_adm group
  replaces -adm account for updating modules in /etc/psi/MX, and
  how to propagate main to the build-* tutorial branches
- module READMEs: fix titles/paths to match module directories
  (DIALS, jfjoch_viewer), replace -adm login steps with unx-mx_adm note

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

DIALS/README.md

@@ -1,11 +1,6 @@
-XDS
+# DIALS
 
-Step 1: login with your -adm account
-
-```
-kinit xxxx_x-adm
-aklog
-```
+Step 1: make sure you are in the `unx-mx_adm` group -- no -adm account needed, members can update the modules in `/etc/psi/MX` directly (if you have problems, please let the admins know)
 
 Step 2: load the latest Pmodules package
 

README.md

@@ -1,10 +1,47 @@
 # MX
 
-This project includes all MX modules in use. 
+This project includes all MX modules in use.
 
 All modules are build with modbuild/2.1.2
 Documentation for how-to-build modules can be found in: https://github.com/Pmodules/Pmodules/wiki
 
+## Pmodules background (from the wiki)
+
+- Modules are organized in hierarchical groups; all modules in this repo belong to the `MX` group (`module use MX`).
+- Filesystem layout: modulefile at `$PREFIX/GROUP/modulefiles/NAME/VERSION`, installation at `$PREFIX/GROUP/NAME/VERSION`, per-version config at `$PREFIX/GROUP/modulefiles/NAME/.config-VERSION` (YAML).
+- Release stages: **unstable**, **stable**, **deprecated**. Newly built modules land in unstable; opt in with `module use unstable`.
+- Pmodules automatically sets `$NAME_DIR`, `$NAME_HOME`, `$NAME_PREFIX`, `$NAME_VERSION` on load and prepends standard directories (`$PREFIX/bin` to `PATH`, `$PREFIX/lib` to `LD_LIBRARY_PATH`, ...) if they exist -- no explicit `setenv`/`prepend-path` needed in the modulefile.
+
+## Permissions
+
+No need to switch to an -adm account any more: members of the `unx-mx_adm` group can update the modules in `/etc/psi/MX` directly. If you run into permission problems, please let the admins know.
+
+## Tutorial branches (build-*)
+
+Each participant works on their own `build-<module>` branch (e.g. `build-dials`). All of them start from `main`.
+
+To propagate new material from `main` to the `build-*` branches:
+
+While the branches are still identical to main (fast-forward, no force needed):
+
+```
+git push origin main:build-dials main:build-buster main:build-careless main:build-crystfel main:build-phenix main:build-pymol main:build-autoproc main:build-xtrapol8
+
+for b in dials buster careless crystfel phenix pymol autoproc xtrapol8; do
+  git branch -f build-$b main
+done
+```
+
+Once the branches have diverged (people committed on them), merge main into each instead:
+
+```
+for b in dials buster careless crystfel phenix pymol autoproc xtrapol8; do
+  git checkout build-$b && git merge main && git push
+done
+git checkout main
+```
+
+If `git push origin main:build-xxx` fails with "non-fast-forward", the branch has its own commits: switch to the merge loop, do not force-push over other people's work.
 
 ## Module tips
 1. modules is name/version (not name/name-version)

alphafold/README.md

@@ -94,9 +94,9 @@ flags.DEFINE_boolean('use_gpu_relax', True, 'Whether to relax on GPU. '
 Add version to files/variants. The version number should match a github tag
 (e.g. `v2.0.1`) or else have the commit hash as `$V_RELEASE`.
 
-As admin user:
+As a member of the `unx-mx_adm` group (no -adm account needed; if you have problems, please let the admins know):
 ```
-cd MX/alphafold
+cd alphafold
 ./build <version>
 ```
 

autoPROC/README.md

@@ -8,12 +8,7 @@ dependencies.
 
 ## Build on Ra
 
-Step 1: login with your `-adm` account
-
-```
-kinit xxxx_x-adm
-aklog
-```
+Step 1: make sure you are in the `unx-mx_adm` group -- no -adm account needed, members can update the modules in `/etc/psi/MX` directly (if you have problems, please let the admins know)
 
 Step 2: load the latest Pmodules package
 

jfjoch_viewer/README.md

@@ -1,11 +1,6 @@
-jfjviewer
+# jfjoch_viewer
 
-Step 1: login with your -adm account
-
-```
-[smith_k@ra-l-005 xds]$ kinit smith_k-adm
-[smith_k@ra-l-005 xds]$ aklog
-```
+Step 1: make sure you are in the `unx-mx_adm` group -- no -adm account needed, members can update the modules in `/etc/psi/MX` directly (if you have problems, please let the admins know)
 
 Step 2: load the latest Pmodules package
 
@@ -14,10 +9,10 @@ module use unstable
 module load Pmodules/1.1.20
 ```
 
-Step 3: go into xds directory, update config.yaml to add newest release version and build module with that release name (e.g. below is for 20240724)
+Step 3: go into jfjoch_viewer directory, update config.yaml to add newest release version and build module with that release name
 
 ```
-cd jfjviewer
+cd jfjoch_viewer
 vi files/config.yaml
 ./build 1.0.0-rc.156
 ```

xds/README.md

@@ -1,11 +1,6 @@
-XDS
+# XDS
 
-Step 1: login with your -adm account
-
-```
-[smith_k@ra-l-005 xds]$ kinit smith_k-adm
-[smith_k@ra-l-005 xds]$ aklog
-```
+Step 1: make sure you are in the `unx-mx_adm` group -- no -adm account needed, members can update the modules in `/etc/psi/MX` directly (if you have problems, please let the admins know)
 
 Step 2: load the latest Pmodules package