Skip to content

Instantly share code, notes, and snippets.

@jjdonson

jjdonson/00-README.md

Last active February 14, 2023 14:52
Show Gist options
  • Save jjdonson/725957b559e115b07193cde3fb75b926 to your computer and use it in GitHub Desktop.
Save jjdonson/725957b559e115b07193cde3fb75b926 to your computer and use it in GitHub Desktop.
Download ZIP
OpenSourceDevTeamFoundations
Raw
00-README.md

Table of Contents

  • Side Notes:
    • Getting To Simple Can Be Complex.
    • Pave Roads, So That Others May Drive.
    • There Are Many Ways To The Mountain Top.

Quick Start For Linux + OSX Users

  • Work-In-Progress Tasks:

    • 1: Skim this doc and comment below, including file:line references.
    • 2: Indicate Chosen Role: devs admins tpms creatives trainers ...
    • 3: Report, document and share all onboarding friction and best practices.
    • 4: Review the gihub markdown (ghmd) code behind this gist by clicking on the [Raw] button on the upper right.

  • Share Basic Details Privately:

    • 1: Local desktop year + operating system + version. We support all desktop operating systems.
    • 2: Software development language(s) of interest. We support all software development languages.
    • 3: When are your most convenient regular times for support and training?
    • 4: Would you like to work solo, paired or on a team?

  • Stage 1: Open Source Software Developer - Github 101

    • Register For Your Free Github Account.
      • Verify by sharing your github login id here: Open Source Web Dev FB Group.
      • Inquire about github profile templates + analytics.
      • Inquire about github markdown and github pages. NO HTML NEEDED!
      • Learn how to barter by contributing to open source github projects.

  • Role Descriptions

    • Devs code to build apps, and devs are identified by: software development language(s) and framework(s)

    • Admins support systems + services + users + data, on-premise and in the cloud.

    • Engineers stand up infrastructure + provide custom security + testing + automation + tool-building.

    • Tech Project Managers support projects and teams with onboarding + task management + workflow analytics.

    • Creatives include photographers + illustrators + user interface designers + musicians + etc.

    • Trainers build and support labs for both teaching and learning curriculum + instruction + assessment

    • Stakeholders own the deliverables for an organization or business.

    • Lawyers, journalists and community activists might test and discover where github workflows and transparency are healthy for democracy.

  • NOTES ON ROLES + TOOLS:

    • Devs and admins MUST do git on the command line.
    • Creatives can use the desktop app.
    • The key to team github skill-building is to learn to use the team dev dojo to learn:
      • How to break things.
      • How to fix those things.
      • How team dev best practices allow those problems to thereafter be prevented.

  • Stage 2: Install Gnu Tools Locally

  • Stage 2 Tests: Local Gnu Tools

    • Local bash shell $ bash --version

    • Homebrew Health $ brew doctor

    • Gnu Utils Installed + Configured $ date --version | grep -i gnu || ( which date && echo 'date GNOT GNU!' )

    • Git Installed + Configured $ git version ; git config --list

Crucial Git Facts

  • What is git:

    • Git is versioning software used by software developers to version code or any type of file.

  • Who made git:

    • In the 1990's, Linus Torwalds built git to support his open source software project, the linux ketnel.

  • Why learn git:

    • Because versioning files and folders on our computers allows us to protect / retain / share all of our work.
    • Because git supports all kinds of files, including very large files.
    • Because git is the local command-line client to the many services that run on github.com.

Crucial Github Facts

  • What is github:

    • Github.com is a web site built to help devs share and collaborate in public or private software code projects.

  • Why learn github:

    • Because all kinds of tools across dev languages are available on github for free, including the git source code itself.

    • Because team dev using local git and remote github is how most remote dev work is tested, reviewed and submitted.

    • Because github makes open source software development collaborative.

    • Because github.com automation and AI tools are excellent.

    • Common Github Quick Start Hurdles Include:

Run Gnu Tools Locally

  • We want to verify that the gnu tools are running: $ date --version | grep -i gnu
  • bash $ bash --version
  • git $ git version; git config --list
  • python3 $ python3 --version; python3 -m platform

Three Levels To Reach Pro Git Ops Team Dev Skills

  • Print out this diagram and inquire about workflow cycles, step testing and step undo options.

  • Git Ops Skill Levels:

    • 1: Git Ops Solo Local => See Solo Local Workflow Cycle Diagram !!

    • 2: Git Ops Solo Remote

    • 3: Git Ops Team Dev

    • 4: Git Ops Teams Admin

  • Git Ops Skills Matrix
  • Open Source Git + Github Training Skill Levels Table
Skills Level Descriptions Git Sub-Commands
1 Solo Local Git Ops version config status init add rm mv commit sha log diff reset stash amend
2 Solo Remote Git Ops clone pull push fork patch issue branch tag merge rebase
3 Team Dev Git ops diff tdd mfa4 bashTests bashLogs bashTpls

Git Ops Training Jumpstarts

  • Prereqs

    • Report any system stability issues and/or browser stability issues.

    • Install + configure local git.

    • Register for a free github id and connect to github.

    • NOTE: ssh must be set up right in order to push code to a github project. (level 2 git ops training)

  • 1: Jump into gitpod, unless browser issues get in the way.

    • Prerequisites: github free account + stable browser login to github

    • Get Started: Request scheduled 30 minute bash paired programming session using gitpod.

    • What Will We Do?

  • Start with a gist like this to learn some basic github markdown (ghmd).

    • Use bash and git and vscode together in a gitpod session.

    • Show how our session changes can be tracked and versioned in a github repo.

    • Barter for paving services (gives) while you learn to drive (gets).

    • Drive the entire process with docs and testing.

    • Diagram the entire process for accelerated training.

    • Create git ops docs using ghmd on github for the Win crowd.

    • Enable github pages for that repo, and choose a jekyll theme.

    • Look at i18n tools for Github Pages.

  • 3: Standing up vm with vbox running ubuntu is another option.
  • Prerequisites: virtualBox
  • Get Started:
    • Install vBox locally.
    • Restart desktop.
    • Create local vBox virtual machine (vm).
    • Deploy Linux Image on vm. (or Windows!!)
    • Connect to linux running on vm using ssh from Git4Windows console.
      • Find free windows terminal apps.
  • 4: Git4Win is better than WSL until proven otherwise.
    • Prerequisites: Might be wise to mess with a windows vm on vBox?
    • Get Started: Since Git4Win can be completely installed into WIN_USER storage, it is easy to remove COMPLETELY!!
    • The ssh key generate + configs + connect2github tests are usually the most troublesome.
  • NOTE:
    • Devs can get started with Level 1 of 3 with ANY of the above setups.
    • Admins should have all of these running
    • devs can use any
    • admins should use all
    • Learn about github doc formatting style guides.

Local Desktop Development Environment

  • All four tools above ought to be TILED as indicated below!!!
Desktop File Explorer Terminal Console
Code Editor Chrome Browser

Screen Shot 2023-02-04 at 8 41 14 AM

Configuring Command Line Tools

Extra Support For Windows Users

  • Microsoft Roadmap in 2023: github + azure

  • some git history is revealing!!!

  • Azure Linux Vms Are > 50% of the Azure VM Fleet

  • WinSCP is scriptable!

  • Free Win screenshot software

  • Remember that most win users know NONE of this stuff, and msoft NOW OWNS github!!

  • Microsoft now owns github and azure.

    • Microsoft staff will be migrating their sofwtare projects from VisualSourceSafe to Github over the next several years.
    • Several github competitors exist:
      • bitbucket.org
      • gitlab.com
      • gogs

  • Bartering start with creating a bartering ladder, where trading is of mutual interest.

  • Admins could trade GIVES ( training ) for GETS ( docs + testing + code reviews ).

  • Admins could perhaps trade training for free cloud hosting credits.

    • microsoft azure:

  • digital ocean:

  • amazon web services:


Google Cloud Platform

Gist Repo Root Page Index

Raw
01-git-help.md 
$ git
usage: git [-v | --version] [-h | --help] [-C <path>] [-c <name>=<value>]
           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
           [-p | --paginate | -P | --no-pager] [--no-replace-objects] [--bare]
           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
           [--super-prefix=<path>] [--config-env=<name>=<envvar>]
           <command> [<args>]

These are common Git commands used in various situations:

start a working area (see also: git help tutorial)
   clone     Clone a repository into a new directory
   init      Create an empty Git repository or reinitialize an existing one

work on the current change (see also: git help everyday)
   add       Add file contents to the index
   mv        Move or rename a file, a directory, or a symlink
   restore   Restore working tree files
   rm        Remove files from the working tree and from the index

examine the history and state (see also: git help revisions)
   bisect    Use binary search to find the commit that introduced a bug
   diff      Show changes between commits, commit and working tree, etc
   grep      Print lines matching a pattern
   log       Show commit logs
   show      Show various types of objects
   status    Show the working tree status

grow, mark and tweak your common history
   branch    List, create, or delete branches
   commit    Record changes to the repository
   merge     Join two or more development histories together
   rebase    Reapply commits on top of another base tip
   reset     Reset current HEAD to the specified state
   switch    Switch branches
   tag       Create, list, delete or verify a tag object signed with GPG

collaborate (see also: git help workflows)
   fetch     Download objects and refs from another repository
   pull      Fetch from and integrate with another repository or a local branch
   push      Update remote refs along with associated objects

'git help -a' and 'git help -g' list available subcommands and some
concept guides. See 'git help <command>' or 'git help <concept>'
to read about a specific subcommand or concept.
See 'git help git' for an overview of the system.
Raw
02-admin-tools.md

Copied from fb chat

  • We could even do a .NET app

  • But I would want to do that on Linux with dotNETCore+SQLServer.

  • the idea is to help win folks understand how the world has changed (!!)

  • and how to get a grip on the emerging future of open source

  • they get a little for free, but then must barter to get the real goods 🙂

  • The bash skills you will need are listed here: https://realpython.com/courses/using-terminal-linux/

  • Barter is a mix of mutual GIVE and GET. One must first give in order to get.

  • You can GIVE by performing certain small tasks, like helping on my fb groups and pages.

  • Or by helping with win user docs.

  • Or by testing things on local windows vm with 2cpu and 1GB RAM.

  • Use that solo local git training diagram for git commands that you can test...

  • You will want to use and support all three:

    • 1: Local desktop git (git4win)
    • 2: Local VMs (vbox/vagrant)
    • 3: Docker => Gitpods

  • Hopefully we will make some bash scripts together. That would be best in gitpod

  • Remember that tiling 4 apps on small screen shows them how to make the most of the least in terms of real estate.

  • Documenting all 4 ways to do open source app dev for Win users is big biz.

  • Open Source Foundation is built on:

    • bash 3.x+
    • git 2.x+ => GITHUB!! $ git version

  • ssh

$ ssh -V
  • python3.9+
$ python3 -m platform
$ python3 --version
  • docker v 20.x+
$ docker --version
  • Here are the base binary version checks
$ bash --version
$ git version
$ ssh -V
$ python3 -m platform
$ python3 --version
$ docker --version

  • Show me the output of each of those bash statements.

  • And then you can paste all of that into a script called. "oss-versions.sh"

  • Run that script like this: $ bash oss-versions.sh

  • We can work on that bash script on github by testing it on:

    • windows
    • ubuntu
    • gitpod

  • Let me know when you are ready and we will work on the web with gitpod, testing bash scripts....

  • paired programming patterns are amazingly effective - so I will role play that from two browsers, so it looks like two different users 🙂

  • FB Post

  • Solo Local Git Workflow Diagram

  • Here is an invitation to my gitpod org... https://gitpod.io/orgs/join?inviteId=165e934c-751f-457d-8e96-e5672fd7d171

  • we should just start with bash and gitpod - paired

  • 1: Git4Win

  • 2: Ubuntu Local VM

  • 3: Gitpod => We should start here.

  • remember that simple barter app is smart move as a tool we might use

  • there are like a billion win devs who need to learn to use git and github

  • We ought to talk through that diagram...

  • That diagram represents level 1 of 3:

  • 1: Level 1 - solo local git

    • git commands => version, config, status, init, clone, add, diff, commit, log

  • Start here and look at solo local git workflow diagram!!

  • 2: Level 2 - solo remote git + github

    • git commands => remote, branch, merge, pull, push, fork
    • sweet github profile templates

  • 3: Level 3 - team dev using git + github

    • github pages + ghmd
    • pull = fetch + merge
    • push
    • conflicts
    • fork
    • github repo pull requests

  • well, what we really want is a diagram that shows both forwards and reverse ...

    • that diagram is mostly forwards-only

  • Mihai: reverse? why?

  • Jeremy: because sometimes we want to undo stuff

  • Mihai: ohh, i thought undo is a separate action

  • JeremyL Undo steps look like this....

    • Step: Create folder and turn it into a local git repo.

    • Undo Step: Turn local git repo back into a regular folder.

    • We can walk through entire cycle, and then step backwards in many steps....

    • Or we can test our way through step at a time, doing and undoing....

  • Jeremy: Look at the diagram, because there is an undo section there!!!

    • Step: Create folder and turn it into a local git repo.
    • Undo Step: Turn local git repo back into a regular folder.

  • Mihai: Shouldn't we use the reset --head command?

  • Jeremy: we can learn that later <nods. first we need to learn the basics

  • Mihai: aa ok

  • Jeremy: HEAD is a great concept

  • The barter option is to help me improve the diagram. It is informative and accurate....

    • ... and it is a good start

  • Mihai: Wo thats why you used the remove everything in the folder approach?

  • Jeremy: Yes, but the diagram must be improved to reflect reversability at every step.

    • Everything in that diagram is solo and local: no github + no sharing

  • Mihai: yeah

  • Jeremy: Three levels of git training skills...

    • Level 1 - solo local git

      • git commands => version, config, status, init, clone, add, diff, commit, log

    • Level 2 - solo remote git + github

      • git commands => remote, branch, merge, pull, push, fork

    • Level 3 - team dev using git + github

      • github pages + ghmd
      • pull = fetch + merge
      • push
      • conflicts
      • fork
      • github repo pull requests
      • sweet github profile templates

  • That ought to be set up as markdown doc page....

  • Mihai: So we need a bash script that follows the diagram? with different commands?

  • Jeremy: Yes, but first we need some more bash statements to fill in how to undo things.

    • how do we test each step?
    • then how do we undo, and test the undo
    • that is a SUB-cycle
    • toggling a step back and forth 🙂
    • at first work in a directory in git4win
$ mkdir ~/repo-dir
$ cd ~/repo-dir
  • use git to turn it into a repo:
$ git init
  • Some tests:
$ pwd
$ ls -al
$ git status
  • The lesson is to find a new subdir: .git
    • That is created when we
$ git init

in a dir

  • The diagram shows how to undo the conversion of a dir into a repo....

  • That is a little cycle of its own on the left side.

  • Mihai: ok.

  • Jeremy: We rarely look into the .git subfolder. But we can:

$ ls .git

  • All version info is kept in there. It can get enormous.

  • Mihai: i get the diagram. You made it fool proof.

    • Now, what should we build?
    • Will it be a script for users to execute the diagram?

  • The diagram first step is completely clear - step forwards... step back

    • we would like that kind of clarity at every step
    • every step has an undo option
    • and testing tells us whether we have stepped forwards or backwards

  • this will build a solid solo local skill set => then git remote dev gets easy!!

    • and team stuff gets interesting

  • Anything we write in bash can be thrown into a bash script and run

    • Meanwhile, manual typing and testing is how to get that smooth first...
    • it is also juicy to add that any bash script can be written as a template....
echo '#!/bin/bash

# bash script autogenerated using the echo command

mkdir -p ~/test-dir; cd $_; pwd
git status
git init
git status
echo "some text" > file.txt
git status'  > script.sh

bash  script.sh

  • Improving the diagrams and paving the road for solo local git training is the first big step....

  • Then we would reuse those same sensibilities for solo remote and team dev training docs

  • Mihai: Ah, ok so we should improve the diagram!!

  • Jeremy: YES! Improving the diagram and creating three tables of contents would be a great start!!

    • On the side I will show you how to script in bash.....
    • But we want to get you thru solo reomte and team dev so we can collab on github.

  • Mihai: Tell me... gitpod is global or just US-constrained? Seems to crash my browser on ghub login :/

  • Jeremy: Gitpod is a shortcut to collaboration on github using a web service

    • That is level 4

  • Mihai: but logging into gitpod is using github account?

  • Jeremy: YES, to use gitpod we need github login access...

    • Similarly we need github access to create gists.
    • ALMOST Similarly, we need cloud storage access to create diagrams using diagrams.net

  • Level 1 - solo local git

  • Level 2 - solo remote git + github => you will need to be able to push to github in level 2

  • Level 3 - team dev using git + github

  • Level 4: gitpod paired programming

  • Mihai: ok... so lets go level 1 for now

  • Jeremy: we should also troubleshoot your issues, but yes, that is easy to get started locally

    • now, the app to build is a simple barter app
    • then we can build on these training lessons
    • EVERY windows dev needs this... EVERY single one

  • Mihai: yeah...

  • Jeremy: if we pave the road, they will drive

  • Mihai: soo did you made a place were we put this stuff? a slock , a trello

  • best would be on github in a public repo

    • most of the old effort is on bitbucket

  • Mihai: ok - i got it

  • Jeremy: take your time and ask questions...

    • An additional tool you will want to install.....
$ gh

  • It is the local tool for interacting with the github api

  • Mihai: oh the github cli

  • git is a cli tool and we can use git to interact with github api in limited ways

  • gh suffers none of those limitations 🙂

    • github team admin client for github api

  • Mihai: i see. i am reluctant to install anything into windows...

  • Jeremy: Then install gh into ubuntu on vm?

    • so your next step is to try to install $ gh
    • and then let me know what version and such
    • gh will inherit git ssh and other configs

  • Remember that the app is barter, where the GIVE and the GET trade should be clear.

  • All devs need to learn to use git and github.

  • Some devs will want to also learn gh

    • we would include gh training in level 2 for those "admin-minded devs"

  • that was a great start, Mihai!

    • I am copying this entire chat session into a gist.....
    • I suggest that you print out that diagram and make notes on it.

  • And we should work on the gist together so you learn some ghmd.

  • Next Step Tasks

    • install gh
    • show gh version and help
    • print diagram
    • review gist
    • discuss undos
    • improve diagram

  • Ask questions

  • expert level 1 techniques would include test-driven coding techniques (y)

    • It does not matter which dev language!!!

  • Theoretically, someone else would come along, in need of training thru level 3.

    • Any dev language they use or want to learn is wide open!!

  • Barter options would allow them to be able to contribute, minimizing the costs of those training and support services.

  • The whole idea is to turn the process of learning open source into some trading options...

  • Barterable open source training services...

    • diagrams
    • testing
    • docs
    • training
    • support
Raw
03-gh-help.md 
$ gh
Work seamlessly with GitHub from the command line.

USAGE
  gh <command> <subcommand> [flags]

CORE COMMANDS
  auth:        Authenticate gh and git with GitHub
  browse:      Open the repository in the browser
  codespace:   Connect to and manage codespaces
  gist:        Manage gists
  issue:       Manage issues
  pr:          Manage pull requests
  release:     Manage releases
  repo:        Manage repositories

GITHUB ACTIONS COMMANDS
  run:         View details about workflow runs
  workflow:    View details about GitHub Actions workflows

ADDITIONAL COMMANDS
  alias:       Create command shortcuts
  api:         Make an authenticated GitHub API request
  completion:  Generate shell completion scripts
  config:      Manage configuration for gh
  extension:   Manage gh extensions
  gpg-key:     Manage GPG keys
  label:       Manage labels
  search:      Search for repositories, issues, and pull requests
  secret:      Manage GitHub secrets
  ssh-key:     Manage SSH keys
  status:      Print information about relevant issues, pull requests, and notifications across repositories

HELP TOPICS
  actions:     Learn about working with GitHub Actions
  environment: Environment variables that can be used with gh
  exit-codes:  Exit codes used by gh
  formatting:  Formatting options for JSON data exported from gh
  mintty:      Information about using gh with MinTTY
  reference:   A comprehensive reference of all gh commands

FLAGS
  --help      Show help for command
  --version   Show gh version

EXAMPLES
  $ gh issue create
  $ gh repo clone cli/cli
  $ gh pr checkout 321

LEARN MORE
  Use 'gh <command> <subcommand> --help' for more information about a command.
  Read the manual at https://cli.github.com/manual
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment