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/: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 or Git Lab
:re `Git Hub`seehttps://github.com/Michael-Allan?tab=repositories:re `Git Lab`seehttps://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
+ 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 )
:re `private branch`see`private .reluk.ca. branch`@`^^• .~/project/.$`@`^*repository collections$`+ 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`>+ 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
: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*\◦+ 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
:seehttps://github.com/search/ Limiting the search by clicking *Topics* at top left.
◦+ Releases: *unchecked*
◦+ Packages: *unchecked*
◦+ Deployments: *unchecked*
§ Settings
§ Options
§ Features
◦+ Wikis: *unchecked*
◦+ Issues: *unchecked*
\◦+ Sponsorships: *unchecked*\◦+ Preserve this repository: *checked*\◦+ Discussions: *unchecked*\\◦+ Projects: *unchecked*
\§+ Branches\◦+ Default branch: reluk.ca\\>+ 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.
: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$`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.”
: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>+ 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 `\+`seehttps://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: