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
                      \\ Leaving these at their default values, as shown.
                    + 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*
                          \\ Leaving these at their default values, as shown.
                            ◦+ 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
                          \\ ↑ Only in those rare cases where `s` might (and then does) reveal changes
                                >+ 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 vs. compound
            - 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: