Manual of maintenance tasks for current projects      - Instructions (to me) on maintaining my current work projects.   reluk.ca   ┌────────────┐   │ ~/project/ │   └────────────┘   │ reluk.ca   ▲ ▼   master │   ┏━━━━━━━━━┓ ┌────────┐ ┌─────────┐   ┃ ~/work/ ┃ ──▶ │ public │ ──▶ │ Git Hub │ or Git Lab   ┗━━━━━━━━━┛ └────────┘ └─────────┘   master master      : re `Git Hub` N.B. `^*/ Browsability is the sole purpose here`      repository collections      - Collections of my project repositories under revision control.      - Each collection contains multiple repositories, one per project, so that each project has one repository in each collection.      `~/project/`      : see ~/project/      : see http://reluk.ca/project/      - Here each repository has a copy of my private `reluk.ca` branch checked out, which gets published as a flat, human readable copy.      `~/work/`      : see ~/work/      - Here each repository has my working copy of the `master` branch checked out.      public      : see ~/var/repo/git/      - Here each repository is a bare clone which gets published as a tool readable copy.      Git Hub or Git Lab      : re `Git Hub` see https://github.com/Michael-Allan?tab=repositories      : re `Git Lab` see https://gitlab.com/users/Michael_Allan/projects      - Here each repository is human browsable as such, with the `master` branch checked out by default.      / Browsability is the sole purpose here; I limit my risk exposure (in the sense of platform dependency) to just that feature.      : re `risk exposure` see e.g. https://openjdk.java.net/jeps/369#Risks-and-Assumptions : also for ways of mitigating risk (in case further exposure is ever considered)      branches      : see also _/project_template/      `master`      `reluk.ca`      - My standing, private fork of the `master` branch.      ━━━━━━━━━━━━ Committing ────────────      + Ensure no test code is uncommented or otherwise active.      >+ e /usr/local/bin/zz-grep      + Expose the appropriate lines.      / In § Base directories and § Filtration criteria.      >+ zz-grep '\bTEST\b' | less      >+ s      - one of:      >+ git add FILES      >+ git add --interactive      What now >+ u      Update >+ COMMANDS      / `A-B,C,D-E for example, or `-A-B,C,D-E` to undo.      Update >+      / Returning an empty line in order to stage what was updated.      What now >+ q      >+ s      >+ git commit      ━━━━━━━━ Making a new project ────────      unless( already the work directory exists )      >+ mkdir --parents ~/work/SUR/SUBNAME      : re `SUR/SUBNAME` see `simple vs\..compound` @ `^+Notes$`      >+ pushd ~/work/SUR/SUBNAME/      if( the token name of the project will be unconventional in form )      >+ e ~/sys/bin/project-*      + Add to both files an ‘exceptional case’ to cover it.      `~/work/`      : see @ `^*repository collections$`      >+ git init && chmod go-wxr .git      / Makes an empty repository regardless of any files present.      configuration      / `.git/config`      >+ git config core.excludesFile ~/work/_/git-core.excludesFile[_minimal]      - Further exclusion of unchecked files:      >+ s      if( further exclusion is wanted )      >+ e .git/info/exclude      remote repositories      / `.git/config`      >+ git remote --verbose      / Expect none.      >+ git remote add public blocked      >+ git remote set-url --push public ~/var/repo/git/`project-token-name`.git/      >+ git remote --verbose      initial content \ Eagerly, else the `git branch` commands below fail with, \ “Not a valid object name: 'master'”.      >+ cp --no-clobber --no-dereference ~/work/_/project_template/1_master/* .      + Remove any inappropriate files.      `project_installation.brec`      + Remove any part that will be inapplicable, or delete the whole file if it comes to that.      + Ensure the editorial comment is removed from the *initial set-up* section.      >+ shopt -s extglob # Set `extglob` option      >+ e !(*.md)      / All but link `README.md`.      + Fill in the project variables, viz. where capitalized.      / Those appearing in several files are `YEAR`, `PROJECT NAME`, `SUR.SUBNAME` and `SUR/SUBNAME`.      : re `SUR.SUBNAME` see `simple vs\..compound` @ `^+Notes$`      - Note that `SUR.SUBNAME` must be filled by the token name.      / Usually the token name is the proper package name, but not always.      : see ~/sys/bin/project-token-name      >+ shopt -u extglob # Unset      if( the project needs no private branch )      : re `private branch` see `private .reluk.ca. branch` @ `^^.~/project/.$` @ `^*repository collections$`      + Initialize the readme file.      : q.v. @ `^*\`~/project/\`$` @ `^^Making a new project$`i      + Commit these boilerplate files, together with any other initial content.      / ‘Project boilerplate[, initial content].’      : see `^+Committing$`      `~/project/`      : see @ `^*repository collections$`      if( the project needs no private branch )      : cf. @ `^*• initial content` @ `^*\`~/work/\`$` @ `^^Making a new project$`i      + Ensure the project’s `~/work/` repository (present directory) is soft-linked from the `~/project/` directory.      + Skip the rest of this section.      >+ ls --directory ~/project/`project-proper-path`      if( already a directory exists there )      + Confirm the directory is really only a soft link to the `~/work/` repository.      >+ rm ~/project/`project-proper-path`      >+ git clone . ~/project/`project-proper-path`/      >+ pushd ~/project/`project-proper-path`/      >+ chmod go-wxr .git      configuration      / `.git/config`      >+ git config core.excludesFile ~/work/_/git-core.excludesFile[_minimal]      >+ ln --force --symbolic ~/work/`project-proper-path`/.git/info/exclude .git/info/      branch `reluk.ca`      >+ git branch reluk.ca master      >+ git checkout reluk.ca      initial content      >+ ln --force --symbolic ~/work/`project-proper-path`/notes.brec      / Even if the target is publicly inaccessible, this link will sit harmlessly.      if( a `build-all` script is present )      >+ ln --force --symbolic ~/work/`project-proper-path`/build-all      + Initialize the readme file.      / Manually merging content from the standard template as follows.      >+ e README.html ~/work/_/project_template/2_reluk.ca/README.html      + Append from the template, overwriting the last line of the original.      if( `project_installation.brec` is not present )      + Cleanly remove the `li` element that refers to it.      + Fill in project variables `SUR.SUBNAME` and `SUR/SUBNAME`.      : re `SUR.SUBNAME` see `simple vs\..compound` @ `^+Notes$`      - Note that `SUR.SUBNAME` must be filled by the token name.      : join @ `^*\+ Fill in the project variables`      + Manually retarget to the corresponding image siblings at `reluk.ca` all hyperlinks to local Breccian source files.      / For sake of their readability when accessed via GitHub `README.md` files; because these hyperlinks are automatically retargeted only when the readme file is served from `reluk.ca`, not GitHub.      : re `automatically retargeted` see ~/work/Web/autoindex/index.js      >+ git add README.html      >+ git commit      / ‘Personalization.’      : see `^+Committing$` \ >+ git push ~/work/`project-proper-path`/ +reluk.ca:reluk.ca --force-with-lease \ : see @ `^^Publication$`i      >+ git push origin +reluk.ca --force-with-lease      : see @ `^^Publication$`i      >+ popd      if( the first component the project’s proper path lacks an entry in the editable tools’ private branch sections )      / Viz. those of `ls /usr/local/bin/zz-*`.      + Add an entry there.      if( the first component the project’s proper path lacks an entry in the *Current projects* section of the logger configuration )      : privately see /opt/_/java-logging.properties      + Consider adding an entry there.      + Add an entry to `survey-repositories`.      : see ~/sys/bin/survey-repositories      ──────── clones ┈┈┈┈┈┈┈┈      public      : see @ `^*repository collections$`      >+ git clone --bare . ~/var/repo/git/`project-token-name`.git      >+ pushd ~/var/repo/git/`project-token-name`.git/      remote repositories      / `.git/config`      >+ git remote --verbose      >+ git remote set-url --push origin blocked      : see http://stackoverflow.com/questions/7556155/git-set-up-a-fetch-only-remote      >+ git remote add github blocked      >+ (d=`realpath .`; n=`basename $d`; git remote set-url --push github git@github.com:Michael-Allan/$n)      >+ git remote --verbose      / Showing the changes.      >+ popd      Git Hub      : see @ `^*repository collections$`      <+ https://github.com/Michael-Allan?tab=repositories      + Press the green button ‘New’.      - There filling in:      + Repository name: `SUR.SUBNAME`      : re `SUR\.SUBNAME` see `simple vs\..compound` @ `^+Notes$`      - Note that `SUR.SUBNAME` must be filled by the token name.      : join @ `^*\+ Fill in the project variables` \ ◦+ Description: *empty* \ ◦+ Public: *checked* \ ◦+ Add a README file: *unchecked* \ ◦+ Add .gitignore: *unchecked* \ ◦+ License: None \\      + Press ‘Create repository’.      + to public      : join `^*→ to public$` @ `^*if.+the \`~/project/\` repository is real` @ `^+Publication$`      / Expect ‘Everything up-to-date’ for all branches.      + thence to Git Hub      / Pushing the initial commitments and so exposing an `Edit` button at the next step.      : join `^*→ thence to Git Hub` @ `^+Publication$`      @https://github.com/Michael-Allan/SUR.SUBNAME      : re `SUR\.SUBNAME` see `simple vs\..compound` @ `^+Notes$`      <+ Refresh the page.      §+ About, by clicking on its gear icon      + Description: ‘SYNOPTIC PHRASE. (mirror)’      + Website: ‘http://reluk.ca/project/SUR/SUBNAME/’      + Topics      : see https://github.com/search      / Limiting the search by clicking *Topics* at top left.      + Releases: *unchecked*      + Packages: *unchecked*      + Deployments: *unchecked*      § Settings      § Features      + Wikis: *unchecked*      + Issues: *unchecked* \ ◦+ Sponsorships: *unchecked* \ ◦+ Preserve this repository: *checked* \ ◦+ Discussions: *unchecked* \\      + Projects: *unchecked*      §+ Default branch: `reluk.ca`      / It retargets Breccian hyperlinks to Web images for sake of readability.      : see `^*\+ Manually retarget` @ `^*• initial content` @ `^*\`~/project/\`$` @ `^^Making a new project$`i      >+ popd      ──────────── finalizing ┈┈┈┈┈┈┈┈┈┈┈┈      + Index the new project.      >+ e ~/work/index.brec      directory description      >+ sudo mount /mnt/lan/server/root/      root >+ e /mnt/lan/server/root/etc/apache2/7_domain/reluk.ca/public/5_in_project_SUR.conf      / Here *SUR* is the topmost component of the proper path.      : see `simple vs\..compound` @ `^+Notes$`      + Insert line:   AddDescription 'SYNOPTIC PHRASE' SUBNAME      >+ sudo umount /mnt/lan/server/root/      @ server      root >+ rc-service apache2 graceful      >+ publish-files      >+ e ~/work/SUR/SUBNAME/project_installation.brec      if( that file exists )      + Test that the project is installable concordant with any instructions.      ━━━━━━━━━━━━━━━━━ Personalization ─────────────────      / Specific to my private branch `reluk.ca`.      >+ pushd ~/work/PROJECT      >+ pushd ~/project/`project-proper-path`/      if( editing )      + Edit.      >+ git commit      : see `^+Committing$`      if( merging all commits into one )      / The private commits, that is.      : see https://stackoverflow.com/a/55102666/2402790      >+ git log --abbrev-commit --decorate --graph --pretty=oneline      >+ git reset --soft origin/HEAD      >+ git diff --staged      >+ git commit      / ‘Personalization.’      : see `^+Committing$`      + to `~/work/`      : join `^*↓ thence back to .~/work/.$` @ `^+Publication$`      >+ popd      ━━━━━━━━━━━━━ Publication ─────────────      >+ survey-repositories      for( each project shown to need it )      >+ pushd ~/work/SUR/SUBNAME/      : re `SUR/SUBNAME` see `simple vs\..compound` @ `^+Notes$`      for( each directory on the `pushd` stack )      >+ s      for( each change-set to commit )      commit+      : join `^+Committing$`      if( you want to save time ) avoiding manual entry of the commands      >+ flow-downstream      >+ popd      continue+ `for`      >+ ls --directory ~/project/`project-proper-path`      if( the `~/project/` repository is real ) no mere soft-link to the `~/work/` repository      to `~/project/`      : re `\`~/project/\`` see `^*\`~/project/\`$` @ `^*repository collections$`      >+ pushd ~/project/`project-proper-path`/      >+ git fetch origin master --verbose      / To `.git/FETCH_HEAD`.      if( it does *not* say ‘up to date’ ) \ >+ s \ >+ git stash \\      >+ git checkout master && git merge --ff-only FETCH_HEAD      >+ git checkout reluk.ca && git rebase master      / Fallible: “It is possible that a merge failure will prevent this process from being completely automatic.”      : see https://git-scm.com/docs/git-rebase \ >+ git stash pop      thence back to `~/work/`      : re `\`~/work/\`` see `^*\`~/work/\`$` @ `^*repository collections$` \ >+ git push ~/work/`project-proper-path`/ +reluk.ca:reluk.ca --force-with-lease      >+ git push origin +reluk.ca --force-with-lease      : ad `\+` : or somehow it fails with ‘stale info’      : re `stale info` see also @ https://stackoverflow.com/questions/39693153      : re `\+` see https://git-scm.com/docs/git-push#Documentation/git-push.txt-ltrefspecgt82308203      >+ popd      to public      : re `public` see `^*• public$` @ `^*repository collections$` \ >+ (c='git push --force-with-lease public'; $c master:master && (echo; $c reluk.ca:reluk.ca))      >+ git push public reluk.ca --force-with-lease      : see `it fails with ‘stale info’$` : In case that ever happens.      >+ git push public --branches      / needs also `--force-with-lease` if commits are to be clobbered (e.g. from rebase or deletion.)      else      to public      : re `public` see `^*• public$` @ `^*repository collections$` \ >+ (c='git push --force-with-lease public'; $c master:master)      >+ git push public --branches      / needs also `--force-with-lease` if commits are to be clobbered (e.g. from rebase or deletion)      thence to Git Hub or Git Lab      : re `Git Hub or Git Lab` see `^*${same}$` @ `^*repository collections$`      if( the project is `MathJax.Emacs` )      >+ (cd ~/var/repo/git/`project-token-name`.git/ && git push gitlab --mirror)      else      >+ (cd ~/var/repo/git/`project-token-name`.git/ && git push github --mirror)      >+ popd      >+ publish-files      ━━━━━━━ Notes ───────      simple vscompound      - Though represented by the compound `SUR/SUBNAME`, the proper path of the project may actually comprise any number of components, or boil down to a single component.      : see `^*proper path$` @ http://reluk.ca/project/glossary.brec \ Local Variables: \ brec-to-collapse-indent-blinds: t \ End: