proto-wayic/_/manual.task - Instructions (personalized)

    ( http://reluk.ca/project/proto-wayic/
    - instructions (to me) on maintaining these proto-wayic projects

    creation`
    - making a project from scratch
    => mkdir ~/code/proto-wayic/NAME
        ( NAME is the simple name of the project
    => pushd ~/code/proto-wayic/NAME/
    + [~/code]
        ( § Repository § [~/code]
        => git init && chmod go-wxr .git
        < configuration  (.git/config)
            => git config core.excludesFile ~/code/proto-wayic/_/git-core.excludesFile
        < remote repositories  (.git/config)
            => git remote --verbose
                < expect none
            => git remote add public blocked
            => (p=`basename $PWD`; git remote set-url --push public ~/var/repo/git/proto-wayic.$p.git)
            => git remote --verbose
        < initial content
            ( eagerly, else 'git branch' commands below will fail, "Not a valid object name: 'master'"
            => cp --no-clobber --no-dereference ../_/project_template/2_master/* .
            => shopt -s extglob # Set `extglob` option
                => e !(*.md)
                    ( all but link README.md
                    - filling in the variables where capitalized
                        ( each of NAME and YEAR are in several files
                => shopt -u extglob # Unset
            =§ committing
                ' Project boilerplate. [Initial content.]
    + [~/project]
        ( § Repository § [~/project]
        => git clone . ~/project/proto-wayic/`basename $PWD`/
        => pushd ~/project/proto-wayic/`basename $PWD`/
            => chmod go-wxr .git
            < configuration  (.git/config)
                => git config core.excludesFile ~/code/proto-wayic/_/git-core.excludesFile
                => ln --force --symbolic ~/code/proto-wayic/`basename $PWD`/.git/info/exclude .git/info/
            < branch reluk.ca
                => git branch reluk.ca master
                => git checkout reluk.ca
            < initial content
                => ln --symbolic ~/code/proto-wayic/`basename $PWD`/project.task
                    ( not often wanted but saves time when it is, and meantime sits harmless
                > e README.html ~/code/proto-wayic/_/project_template/3_reluk.ca/README.html
                    ( manually merging as follows
                    = append from the template
                    = fill in project NAME variable
                =§Repository§ committing
                    ' Personalized boilerplate.
                => git push ~/code/proto-wayic/`basename $PWD` +reluk.ca:reluk.ca --force-with-lease
                    ( '+' to further restrict what it pushes, or somehow it fails with 'stale info'
                        ( git-push(1) § --force
                        ( https://stackoverflow.com/a/41153073/2402790
            => popd
    - clones
        + [public]
            ( § Repository § [public]
            => git clone --bare . ~/var/repo/git/proto-wayic.`basename $PWD`.git
            => pushd ~/var/repo/git/proto-wayic.`basename $PWD`.git/
                < remote repositories  (.git/config)
                    => git remote --verbose
                    => git remote set-url --push origin blocked
                        ( http://stackoverflow.com/questions/7556155/git-set-up-a-fetch-only-remote
                    => git remote add github blocked
                    => (d=`realpath .`; p=`basename $d`; git remote set-url --push github https://github.com/Michael-Allan/$p)
                    => git remote --verbose
                        < showing the changes
                => popd
        + [github]
            ( § Repository § [github]
            < https://github.com/Michael-Allan?tab=repositories
                = [New]
                = fill in
                    - Repository name: proto-wayic.NAME
                  / - Description: *empty*
                  / - Public: checked
                  / - Initialize this repository with a README: unchecked
                  / - Add .gitignore: None
                  / - Add a license: None
                  // leaving these at their default values, as shown
                = [Create]
            =§Repository§ publication § → thence to [github]
                ( so pushing the initial commitments
                - after which an [Edit] button is exposed for the next step
            < https://github.com/Michael-Allan/proto-wayic.NAME
                = [Edit]
                    - Description: Mirror of my proto-wayic.NAME branches
                    - Website: http://reluk.ca/project/proto-wayic/NAME/
                - [Settings]
                    ( as per https://github.com/Michael-Allan/proto-waycast/settings
                    * Features
                        = uncheck Wikis, Issues and Projects
                    * Data services
                        = uncheck Vulnerability alerts
                  / - setting the viewed default to branch reluk.ca
                  // there is no GitHub setting for view default (as opposed to clone default)
                    - that is all, the check buttons are self committing
    =root> mount /mnt/lan/server/root/
        root> e /mnt/lan/server/root/etc/apache2/7_domain/reluk.ca/public/5_in_project_proto.conf
            = insert line
                ' AddDescription 'SYNOPTIC PHRASE' NAME
        =root> umount /mnt/lan/server/root/

    ────────────────────────────────────────────────────────────────────────────────────────────────────
    Repository`
    - repository of project files under revision control
    + [~/project]
        < ~/project/proto-wayic/
        < http://reluk.ca/project/proto-wayic/
        - Web readable copy of the reluk.ca branch (checked out) for each repository
    + [~/code]
        < ~/code/proto-wayic/
        - working copy of the master branch (checked out) for each repository
    + [public]
        < ~/var/repo/git/proto-wayic.*.git
        - tool-readable bare clone of each repository
    + [github]
        < https://github.com/Michael-Allan?tab=repositories
        - Web browsable revision history of each repository
            ( of its master branch by default

    branches`
    ( cf. ./project_template/
    * master
    * reluk.ca
        - my standing, personalized fork of the master branch

    gaining command`
      => pushd ~/code/proto-wayic/NAME/
          ( NAME is the simple name of the project

    committing`
    - `/usr/local/bin/zz-grep` -
        < §§ Base directories + Filtration criteria
            = expose the appropriate lines
        > zz-grep '\bTEST\b' | less
            = ensure no test code is uncommented or otherwise active
    => s
    => git add --interactive|FILES
        =What_now> u
            =Update>> A-B,C,D-E
                < to undo: -A-B,C,D-E
            =Update>>
                < returning an empty line in order to stage what's been updated
        =What_now> q
    => s
    => git commit
        ' Formatting, phrasing[ and so forth].

    personalization`
  / = ensure no uncommitted changes in code repository
  /     - committing them | stashing them | planning to skip § to ~/code, below
  // this cannot matter
    => pushd ~/project/proto-wayic/`basename $PWD`/
        < a working copy of branch reluk.ca is always checked out here
            ( personalized, standing fork
        = edit
            ( it should always be safe to edit, no need to sync with *master* branch first
        =§ committing
        * to ~/code
            => git push ~/code/proto-wayic/`basename $PWD` +reluk.ca:reluk.ca --force-with-lease
                ( '+' 'to further restrict', as per above
        => popd

    publication`
    - `/usr/local/bin/zz-ff` -
        < § Base directories
            = expose the appropriate lines
        < § Repository site overview
            = uncomment
        => zz-ff
    - for each project shown to need it
        => pushd ~/code/proto-wayic/NAME/
            ( NAME is the simple name of the project
    - for each project atop the resulting stack of working directories
        + ↑ to [~/project]
            ( § site § [~/project]
            => pushd ~/project/proto-wayic/`basename $PWD`/
                => git fetch origin master --verbose
                    ( to .git/FETCH_HEAD
                - if it DOESN'T say 'up to date':
                  / => s
                    > git stash # only if *s* reveals changes (rare)
                        => 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."
                                ( git-rebase(1)
                        > git stash pop
                    + ↓ thence back to [~/code]
                        ( § site § [~/code]
                        ( sending back there the rebased reluk.ca branch, that is
                        => git push ~/code/proto-wayic/`basename $PWD` +reluk.ca:reluk.ca --force-with-lease
                            ( '+' 'to further restrict', as per above
                => popd
        + → to [public]
            ( § site § [public]
            => (c='git push --force-with-lease public'; $c master:master && (echo; $c reluk.ca:reluk.ca))
                < if a push fails with 'stale info', then prepend '+' to its refspec
                    ( as per above; failure of both seen on first push to a newly cloned [public]
        + → thence to [github]
            ( § site § [github]
            => (cd ~/var/repo/git/proto-wayic.`basename $PWD`.git && git push github --mirror)
                < pushd ~/var/repo/git/proto-wayic.`basename $PWD`.git/
                < git push github --mirror
                    ( user: Michael-Allan
                < popd
                - Expect error “'blocked_on_removal_from_GitHub' does not appear to be a git repository”
                  if the repository is no longer published on GitHub.
        => popd
    => sudo -u public sync-web

    site`
    - map of sites

                reluk.ca

              [~/project]

           master ↑ ↓  reluk.ca

               [~/code]   →   [public]   →   [github]

                 master                       master


        < [~/path]
            - a repository site identified by its location in the file system
        < [name]
            - a repository site identified by its Git (*remote*) name at other sites
        <  name
            - the branch normally checked out in the repository
                - or the branch of transferred ↑↓ commitments