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/:seehttp://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
:seehttps://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’.
:seehttps://stackoverflow.com/questions/39693153:re `‘\+’ .+ pushes`seehttps://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
:seehttp://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*\\+ 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
:seehttps://github.com/search/ Limiting the search by clicking *Topics* at top left.
◦+ Releases: *unchecked*
◦+ Packages: *unchecked*
\◦+ Environments: *checked*\\§ Settings
§ Options
§ Features
◦+ Wikis: *unchecked*
◦+ Issues: *unchecked*
◦+ Projects: *unchecked*
\§+ Branches\◦+ Default branch: reluk.ca\\>+ 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.
:seehttps://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
continueunless( 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\\>+ 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.”
:seehttps://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