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 │   ┗━━━━━━━━━┛ └────────┘ └─────────┘   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 : see https://github.com/Michael-Allan?tab=repositories - 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 _/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 ━━━━━━━━━━ Creation of a new project ────────── / Making a project from scratch. 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` unless( is waycast ) >+ git config core.excludesFile ~/work/_/git-core.excludesFile - 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'”. if( is waycast ) + Manually copy what is wanted from `~/work/_/project_template/1_master/` and modify it to suit the waycast. else >+ 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 + Commit these boilerplate files, together with any other initial content. / ‘Project boilerplate[, initial content].’ : see `^+Committing$` • `~/project/` : see @ `^*repository collections$` if( is waycast ) >+ ln --symbolic ~/work/`basename $PWD`/ ~/project/ break \ Skipping the rest of this `~/project/` §. >+ ls ~/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 >+ 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`/working_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` >+ git add README.html >+ git commit / ‘Personalization.’ : see `^+Committing$` >+ git push ~/work/`project-proper-path`/ +reluk.ca:reluk.ca --force-with-lease / ‘+’ to further restrict what it pushes, or somehow it fails with ‘stale info’. : see https://stackoverflow.com/questions/39693153 : re `‘\+’ .+ pushes` see https://git-scm.com/docs/git-push#Documentation/git-push.txt---force >+ 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. + Add an entry to the *Current projects* section of the logger configuration. : privately see /opt/_/java-logging.properties + 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* \ ◦+ Choose a license: *unchecked* \\ Leaving these at their default values, as shown. + Press ‘Create repository’. →+ to public / Expect ‘Everything up-to-date’ for both branches. : join `^*→ to public$` @ `^+Publication$` →+ 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 if( is waycast ) ◦+ Description: ‘SYNOPTIC PHRASE. (mirror, liable to rebasing)’ else ◦+ 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* \ ◦+ Environments: *checked* \\ Leaving these at their default values, as shown. § Settings § Options § Features ◦+ Wikis: *unchecked* ◦+ Issues: *unchecked* ◦+ Projects: *unchecked* \ §+ Branches \ ◦+ Default branch: reluk.ca \\ !! It would set the default for pull requests, not merely for viewing. >+ popd ──────────── finalizing ┈┈┈┈┈┈┈┈┈┈┈┈ + Index the new project. >+ e ~/work/way/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 >+ e ~/work/SUR/SUBNAME/project_installation.brec + Test that the project is installable concordant with any instructions. ━━━━━━━━━━━━━━━━━ Personalization ───────────────── / Specific to my private branch `reluk.ca`. / Inapplicable to the waycast. >+ 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$` unless( you want to manually enter the commands ) >+ flow-downstream >+ popd continue unless( is waycast ) ↑ 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 : re `\+reluk\.ca:reluk\.ca` see `^*/ ‘\+’ to further restrict` >+ popd → to public : re `public` see `^*• public$` @ `^*repository collections$` if( is waycast ) >+ (c='git push --force-with-lease public'; $c master:master) else >+ (c='git push --force-with-lease public'; $c master:master && (echo; $c reluk.ca:reluk.ca)) / Should it fail with ‘stale info’, prepend ‘+’ to its `refspec`. : see `^*/ ‘\+’ to further restrict` → thence to Git Hub : re `Git Hub` see `^*• Git Hub$` @ `^*repository collections$` >+ (cd ~/var/repo/git/`project-token-name`.git/ && git push github --mirror) >+ popd >+ publish-web ━━━━━━━ 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/lexicon.brec