Projects:
======Projects======

=====List of Projects=====

Each project is a web app, a subdomain of voyc.com, stored in gitlab (previously github).

=== For Developers ===

[[projects:layout:layout]] - browser screen splitter

[[projects:account:account]] - submodule, user management

[[projects:fx:fx]] - submodule, library of game effects

[[projects:icon:icon]] - submodule, library of icons

[[projects:jslib:jslib]] - library of javascript tools

[[projects:minimal:minimal]] - html, css, javascript for a minimal web app


=== Apps ===

[[projects:homepage:homepage]] - homepage for voyc.com

[[projects:library:library]] - library of web development components

[[projects:pokerface:pokerface]] - facial expressions of artificial feelings

[[projects:geo:geo]] - geopolitics map drawing

[[projects:curriculum:curriculum]] - voycipedia

[[projects:global:global]] - previously voyc, before geo

[[projects:samantha:samantha]] - AI webchat

[[projects:classy:classy]] - comment classifier

[[projects:sandbox:sandbox]] - experiment and demo

[[projects:bahasa:bahasa]] - language

[[projects:flash:flash]] - flash card memorization

[[projects:guru:guru]] - random quote

[[projects:mai:mai]] - language

[[projects:plunder:plunder]] - game added atop voyc

[[projects:sanskrit:sanskrit]] - language

[[projects:robots:robots]] - multiple hardware projects

[[projects:vote:vote]] - ranked choice voting

[[projects:wordnet:wordnet]] - database only, sql version of Princeton's WordNet

[[projects:model:model]] - starter project template

[[projects:timeline:timeline]] - timeline

[[projects:voyc:voyc]] - leftover from when geo/global was voyc.com

[[https://docs.google.com/spreadsheets/d/1Hs1h9R91J8e3biNyIzN-aX_iER-cJ1zTMMGI4BeC-IA/edit?gid=2023137882#gid=2023137882 | My Drive -> sync -> dev -> webapps -> projects checklist sheet]]

[[https://drive.google.com/drive/folders/0ByidsAQcVcUUei0wc1lpVWlfUFU?resourcekey=0-22REggHl5xt3oBQw_syh0w | My Drive -> sync -> dev -> webapps]]

=====Developer Guidelines=====

==== Coding Style ====

Coding style:
  * use the tab character to indent
  * use unix line-endings

javascript

php

python

==== File Organization ====

  project/                        ← git root
    .env
    config.php
    config-example.php
        html/                   ← docroot - index.html
                svc/            ← webservice stubs, php or python
                js/             ← project-specific javascript code
                        lib/    ← generic javascript code
                css/            ← project-specific css styles
                        lib/    ← generic css styles
        php/                    ← project-specific php code
                lib/            ← generic php code
        python/                 ← project-specific python code
                lib/            ← generic python code
        db/
            schema.sql
            seed.sql
            reset.sh

====.gitignore====

  index.php
  min.js
  min.css
  RELEASES.md
  robots.txt
  .well-known/*
  .aider*
  config.php
==== Duplicate Content ====

Most of our projects have a dev and a production version.\\
Example:
  * jslib.voyc.com
  * jslib.hagstrand.com

These two sites have duplicate content.\\
We want to tell the search engines to index prod, not dev.\\
How do we do that?\\

==option 1. robots.txt==
  User-agent: *
  Disallow: /

This prevents the search engines from crawling the site.\\
But it does NOT prevent the search engines from indexing the site.\\

==option 2. html meta==
  <meta name='robots' content='noindex,follow' />

This means that prod and dev will have a different line in index.html.\\
How can I do this dynamically?
The crawlers are probably scraping the HTML without preprocessing javascript or PHP.

==option 3. password==
How do we do that?

==option 4. temporary dev environment==
  * Take care to not allow any links to the dev subdomains.
  - Note that the a2 cpanel domains page has the <meta robots noindex> tag. 
  - When starting server development, manually add the  <meta robots noindex> tag.
  - After completion, delete the worktree, and/or put up a fake page.
  - Maybe we only need one dev subdomain?

====git Structure====

===Five Repository Groups===

^ location  ^ name     ^ git                   ^ purpose                  ^
| gitlab    | gitlab   | voyc/proj.git (bare)  | public git host          |
| a2        | voycgit  | voycgit/proj.git      | central git repository   |
| a2        | webprod  | webprod/proj/.git     | production web host      |
| a2        | webdev   | webdev/proj/.git      | server development       |
| local     | webapps  | webapps/proj/.git     | local development        |

{{:projects:five_repositories.png?900|}}

=== Branches ===

gitlab, voycgit, and webprod have a master branch only.\\
webdev and webapps have a master branch and also a temporary feature branch.

=== Remotes ===
voycgit has no remotes.\\
gitlab has no remotes. \\
All other repositories have remote //origin// pointing to voycgit.\\
webprod also has remote //gitlab//.\\

  get remote -v
  $ origin ssh://voyccom@az1-ss8.a2hosting.com:7822/home/voyccom/voycgit/jslib.git	
  $ gitlab https://gitlab.com/voyc/jslib.git

Note that use the ssh protocol; never the local protocol.

==== voyc git Workflow====

== refresh the local repo and worktree ==
  git clone ssh://voyccom@az1-ss8.a2hosting.com:7822/home/voyccom/voycgit/vote.git
  git branch   # make sure you're in the master branch
  git pull origin master
  git submodule foreach git pull origin master

== start development ==
  git branch popup         # create a feature branch
  git checkout popup

== development ==
  <make changes>
  git status
  git add .
  git commit -m 'New popup architecture'   # version control
  git push origin popup      # remote backup

== pull in simultaneous development from server - ???? ==
  git switch master
  git pull origin master 
  git checkout popup
  git rebase master               # merge modified master into popup branch, resolve conflicts here

== complete development ==
  git checkout master
  git merge popup
  git diff master..popup
  git branch -d popup
  git push origin master      # push to central
  git push origin -d popup   # delete branch from central

== in webprod ==
  git pull origin master
  git push gitlab master

==== voyc release management ====

Trends in release management as of 2026.
  * 50/72 rule. A commit message has three lines (title, blank, body).  The first line is the title and it is 50 characters long.  The second line is blank.  The third and subsequent lines make up the body; they are bullets, and they are 72 characters long.  [Ed. title is my word.  Other people say description or subject.]
  * Conventional Commits.  The first line of the commit message is prefixed with a category: feat, fix, perf, style, refactor, test, build, chore.  This rule overrides an earlier rule that the title should be capitalized.
  * Semantic Versioning.  Each release is numbered major.minor.patch, like 14.3.5. When a development group breaks backward compatibility, now a normalized behavior, they assign a new major number.  When a bug is discovered that is so dangerous it must be fixed immediately, they release a patch.

{{https://en.wikipedia.org/wiki/Conventional_Commits_Specification | more on Conventional Commits}}\\
[[https://semver.org/ | more on Semantic Versioning]] \\
[[https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html | Tim Pope: A Note About Git Commit Messages, 2008.]]\\

At voyc we use these above trends in commit messages and tag messages.  The log of commit messages is detailed for developers.  The list of tag messages is more abstract, for users and managers.  Release histories are generated by script from the list of tag messages.

At deployment, a file named RELEASES.md is generated from the tag messages by a script.  It is not committed; it listed in .gitignore.

[[..:git | more about log and tag]]

  # All tags with their full messages, most recent first
  git tag -l --sort=-version:refname | xargs -I{} git show {} --no-patch --pretty=format:"%tag %*%(tag)%n%s%n%b%n---"
  
  git for-each-ref --sort=-version:refname --format="%(refname:short)%0a%(contents)%0a---" refs/tags


Practices:
  * Commits made only in feature branch.  Never on the master branch.
  * We let aider auto-commit every change.
  * At merge, we generally keep the detailed commits, but squash is optional.
  * The commit log is for developers.
  * At release, we create a tag, observing SemVer, with hand-written message.
  * Public release history is generated from the tag messages.
  * Conventional commits types are used only on the commit messages, not the tag messages.


==== One-time Fix Privacy in Log ====

  # in laptop dev repo
  git checkout fixlog
  git filter-repo --mailmap .mailmap --force
  
  git checkout master
  git merge fixlog
  git branch -d fixlog
  
  git push origin master --force --tags   # push to bare repo
  git push gitlab master --force --tags   # push to gitlab

==== Start Branch ====
  git branch peaceful

==== Save Work ====
  # save work
  git checkout peaceful
  git commit -m 'feat: new feature'
  git push origin peaceful     # push feature branch to bare repo
  
==== End Branch ====
  git checkout master
  #git merge --squash peaceful
  git merge --no-ff peaceful
  git commit -m 'squashed hand-written commit message'
  git branch -D peaceful    # after squash the big -D force is required
  git push origin master     # push master to bare repo
  git push origin --delete peaceful  # delete feature branch from bare repo

==== Deploy ====

  # in local dev
  git tag -a v0.2.0  # with -a and not -m the editor opens for multiline message
  git push origin master --tags
  git push gitlab master --tags  # need PAT
  git for-each-ref --sort=-version:refname --format='%(refname:short)  %(contents)%0a%0a' refs/tags >RELEASES.md
  
  # in production webserver
  git fetch origin
  git reset --hard origin/master