I often read ideas of how to achieve Flow which are more reactive than proactive. The reactive ideas are to close your office door (assuming you have a door), turn off all notifications on your computer (instant messaging notifications, text messages, email, etc), and wearing headphones while listening to ambient music. These are all great ideas, but they are reactive to the situation.

One idea I would like to propose more software engineers to do is to train your brain to focus by practicing meditation.  I find that 10 to 30 minutes of meditation per day are an excellent way to teach my brain how to focus and get into flow.  I've practiced meditation for a little over 4 years now and find it to be a great way to focus.

For those that are not familiar with meditation, it can be as simple as finding a quiet place where you won't be interrupted, usually closing your eyes, focusing on inhaling and exhaling a few times to calm the mind and center it on a single task of focusing on your breath.  At its most simple form, that's really it.

During each session, your monkey mind will likely go skipping off thinking of a hundred different things.  Once you discover that your mind has wandered off (not focused on simply observing of your breathing), just gently bring your mind back to your breathing.  You shouldn't judge yourself harshly as you try to complete this seemingly simple task of observing your breath for 10 to 30 minutes; your monkey mind has been encouraged to wander off seemingly randomly through all of our electronic interruptions.

There are several meditation apps that I have used for learning how to meditate. Each have their own flavor and style of training and doing meditation.  There is no one right way to do it; I would encourage you to just experiment to find something that fits with your style.  Also keep in mind that as you practice meditation, you may find something that works now, but months or years later you shift to something else as you grow and learn.

One app that I currently use daily is "Insight Timer".  There are thousands of guided meditations, meditation background music, and courses.  You can find guided meditations or simply ambient background music to listen to for your meditation. Within Insight Timer, a favorite meditation guide for me is Andy Hobbson.  His guided meditations are my style, but you'll need to find your own style.

Happy meditating...

Software that requires a team is something of significance; not just a side project that many of us work on from time to time.  The software I'm talking about is designed, marketed, architected, built, tested, supported, and deployed for the world to use.  And EVERYONE on this team is important.  There is no single person that is more important than the other because a team is only as strong as its weakest link.  This is also why I like to focus on the team's successes rather than individual contributors.  

Marc Andreessen famously quipped that "software is eating the world" and I believe it. However, I don't quite subscribe to Microsoft's CEO belief that "every company is a software company".  Being a little geeky, that sentence fails the Liskov Substitution Principle; it's more accurate to say that every company has a (or should have a) software development element within it (if you're going to be competitive in the world economy). Software is everywhere and there really isn't an end in sight and building software of any real significance requires a team.

And, like team sports, software teams are comprised of individuals.  The individuals all have their own skills, ambitions, goals, challenges, strengths, and weaknesses.  As such, that team will be all the better when each of the individuals are the best at the skill that the team needs.  It's also a lot more fun when everyone is firing on all cylinders, confident, supported, encouraged by the rest of the team members.

There is nothing wrong with individual sports.  In fact, I have the utmost respect for people that play individual sports.  Just like being on the tennis court, there's no one else to blame. Or, just like being a pilot flying solo.  You have to be on top of your game to be able to do this.

I'm not saying, however, that this team has to literally be in the trenches shoulder to shoulder like Soldiers or like a football team for every play.  But, there has to be enough coordination and communication to ensure that the team is moving in the same direction with the same motivation. A software development team is very cross-functional with a lot of individual specialities.  Those individuals don't need to be spending every working hour constantly communicating because they need time to focus on their task - their specialty - because the team is relying on them.

I love everything about software development and working in a team. And I continue to get the opportunity to work with a lot of great teams. The "knowledge workers", as we are often referred to, appear to go into this abyss and emerge with something.  It's a very creative process.  Whether its a UI design, the front-end client code, the backend APIs, or database structures, they are all have fascinating things to consider;  everything from usability to performance.  

But, team's don't just happen.  They are cultivated.  They are built.  They are led!  

If you think software is hard to build, consider the challenges of building a team. People are the most complex systems I know.  They all have their own operating systems, communication protocols, and networking infrastructure.   They all come with their own "bugs", aka biases.  On top of this, many of these biases are subconscious, which make them even more difficult to identify.

Working with great teams is exhilarating, inspirational, and fun.  I've been part of a few great teams in my career and that feeling is alluring.  The one thing I really appreciated from a strong team is - strangely enough - teamwork.  Specifically, everyone supporting one another.  Encouraging one another.  Helping them get over roadblocks and freely giving them ideas.  Sharing what they learn along the way, regardless of whether or not they think the topic may apply to them.  In my experience, sharing things you learn along the way can result in surprising ways that it can be applied in other areas of the team or company.

Just like a sports team, a software team needs leadership.  Leaders that coach, guide, mentor, encourage, and supports individual members -- as well as the team as a whole. Leadership happens on many different levels.  Leadership is way more than management.  

Everyone gets up in the morning wanting to feel like they are contributing to the team and the goal.  "I'm going to go to work today and fail at my job and make everyone miserable", says no one, ever.

Moreover, people grow and change.  Their goals change.  Life happens.  They mature (hopefully).  It's a leader's job to communicate the direction of the team and the company and help people understand how they can contribute to that goal. It's also a leader's job to encourage individuals to learn new skills and get experience with a new technology to continue that growth so they can continue to be a valuable part of the team.  It's a leader's job to inspire and paint a clear picture.

So, are you playing on a team?  How are you doing in your role on the team to support, encourage, and lift everyone up?

First, I refer to my notebook as a software engineering notebook, rather than a programming or code journal because I try to encourage myself to be systematic, or scientific-lite about it.  Meaning that I have a general collections of sections that I have developed which encourages me to have a structure to the information that I capture.  It helps me remember to capture certain aspects of the things I'm learning or experimenting with.  For example, references for the information I'm writing.

Second, my interests are broader than just "programming" or "coding".  I love all aspects of software engineering!  I love the psychological UI/UX color, typography, animation aspects of applications as much as I do building out CI/CD deployment pipelines, as well as building the application itself.  In my notebooks over the years, I find all of these topics covered in various and interesting ways.

Engineering has been defined in Merriam-Webster as: "the design and manufacture of complex products".  The Wikipedia universe currently defines "software engineering" as, "the systematic application of engineering approaches to the development of software." It may also be my degree in aerospace engineering, that encourages me to approach this from a more scientific approach. But, there are no hard and fast rules for your own software engineering notebook. I'm going to share what I've done and you might adopt it for a while until you decide on how you want to change it up and make it personal for yourself. My format is not rigid and it is never "done"; it is forever changing in ways that I want to experiment.

In the past, however, I kept my software engineering notebook to myself, usually on my personal Atlassian Confluence Wiki.  It's not pretty, but my notebook is just for me.  But, I now realize that there might be times when my notes might be helpful to others.  So, I'm trying to migrate it to a more public format by using this Ghost blog.  

My goal, however, remains the same - to  capture notes for me.  If they help you, great.  If they confuse you, I'm sorry, I may try to help you understand if you contact me, but then again, I'm busy with a lot of my own projects and I may not have time.  Again, these notes are for me.

Typical types of pages that I keep in my electronic notebook: Experiments, Course Notes, Future Blog Topics

Experiments:

While I am learning something new, or trying a new approach, I like to treat it loosely as an experiment.  I like to capture the following as I'm experimenting:

• The "title":  I often find that as I work through the problem, the title I originally assigned often morphs (becomes more specific) as I develop the solution. Naming the problem, like naming variables and functions in software, is often a challenging part of solving it.
• The "problem statement":  More explanation of what I'm trying to accomplish, what I want to learn, the question I'm trying to answer, etc.  
• The initial conditions and assumptions that I'm making.  
• The experiment itself: Documenting where the code (Git repo) and data lives, the commands I'm issuing, and the results I get.  I leave these in to show the chronological progression of my study.  Rarely if ever do I delete them.  I often include inline code blocks of command line commands, the results just get copied and pasted into the notebook.  I've found that many times as I progress through my experimentations, I misinterpreted the results and being able to review the chronological progress at how I arrived here,  I'm able to find the error.  
• Doing this also allows me to learn to diagnose these errors earlier.  For example, how the operating system was trying to tell me one thing, but I misinterpreted it which lead me to an incorrect conclusion or a new hypothesis that I later proved wrong.  I also include screenshots of the browser developer tools (e.g Console) output to show the results.
• In addition, as I progress, I usually develop additional hypothesis, or experiments to try - while I'm working on the current experiment.  So, I capture all of these as I go.  Some I may get to, others may live on until another day. Again, these notes are just for me.
• Lessons learned:  If the topic is sufficiently large or long, I will often summarize "lessons learned" at the top of the topic so that when I return to it, I have my own Cliff Notes (or abstract) for the topic.  Tailored to what I didn't know and therefore were a gap.
• References: I also include links to blogs, books, and conversations used to develop my understanding of the problem, possible approaches, and results that others have obtained.

Course Notes:

When I take a course - Udemy, Pluralsight, Coursera, O'Reilly, etc, I take a lot of notes.  

• It helps me focus on the material rather.  I also take screenshots of the lecture material or website information I find.
• It helps me understand ideas and connect them with concepts from other instructors by making hyperlinks to other entries and discoveries I've made.
• It helps me retain what I learned, not only because the act of typing up the notes, helps make additional connections to other ideas, but it also allows me to return to it and scan it for the things that I didn't know.
• It helps me clear that stuff out of my head knowing that I understand the concepts and I can get back to the details at any time reliably.

The format I use is pretty simple (and although I'm biased) quite logical:

• Course title
• Author
• Date the course was released (or last updated)
• Date I started the course
• Lessons learned (summary)
• Chronological notes of each section; bulleted highlights

Blog Topics:

• This lists the proposed idea, a couple sentences that could be compared to an "abstract", and the date I entered it.

References:

• https://levelup.gitconnected.com/why-programmers-need-a-training-journal-edf2db5be44c
• https://www.sciencemag.org/careers/2019/09/how-keep-lab-notebook
• http://bryanpendleton.blogspot.com/2014/07/git-clone-vs-fork.html?m=1
• https://benjaminhardy.com/how-to-write-in-your-journal-to-improve-yourself-and-achieve-your-goals/
• akin to Bullet Journaling for Programmers: http://www.jacqui.tk/prof-development/why-you-should-keep-a-code-journal-code-journaling-pt-1-of-4/

Manual Steps:

• Modify the angular-cli.json file:  Add serviceWorker": true, in the apps[] portion of this file.
• Add service worker package via npm
• Max then highlights that in order to use Service Workers in Angular, we need to tell Angular to build this as a "Production" build.

npm install --save @angular/service-worker

ng build --prod

Max goes on to explain that when we create a production build, the Angular CLI creates a couple of new files that suggest they are specific to the Service Workers. He also opens up the ngsw-manifest.json file to see what is contained in it and explains that these files are all of this project's static assets (bundled, minified, etc).  It's basically telling the Angular Service Worker that all of these files should be "pre-cached" (aka, "pre-fetched"?).  There is a hash associated with each static asset filename which is used to identify when a new version of this static asset is available.

• Max also notes that the production build also creates a sw-register.xxx file that registers the Angular Service Worker with the application.
• Max then points out the worker-basic.min.js file and says that this is the Service Worker package which is all setup and managed by the Service Worker.
• Max then goes on to point out that the Assets (fonts, icons, etc) are missing at this point (if using his manual process of converting an Angular App to a PWA). To solve this, Max recommends creating an ngsw-manifest.json file at the Project Root directory (not to be confused with the dist/ngsw-manifest.json file that is automatically created by the Production build step).  NOTE: When using the Angular CLI to add PWA functionality as described above, the CLI automatically creates a file called ngsw-config.json that appears to serve as the same functionality, but there are a lot of differences between these two files.
• Next, Max talks about adding a manifest.json file to the assets folder and makes a copy of the content of a manifest file from somewhere into this file, but I don't know where he got it.  Maybe he got it from the "manifest.json" file that he created in the "Manifest" Modules (A hint I see is that the "Instagram as a Progressive Web App" was the original application name) Yup, found it in app-manifest-03--final.zip?  NOTE: In the Angular CLI automatic version (which presumably uses a Schematic to automate all of this), the equivalent file is the src/manifest.webmanifest file.
• Finally, Max adds a <link \> line to add the manifest file to the index.html file.
• Build the new Angular application (production) with the Service Worker information applied: ng build --prod
• Max suggests, however, that it's possible to use ng serve --prod but the Angular Documentation suggests that this is NOT possible.  They say that we must use something like http-server instead. "Because ng serve does not work with service workers, you must use a separate HTTP server to test your project locally." However, ng serve --help suggests that we should be able to use the --prod option because it is still available, but it doesn't say specifically that it supports service workers.  Hmmm?

Q?: Would the manual steps outlined by Max work for AngularJS applications too?

First, start by creating a new Angular CLI project:

$ ng new <project-name>
$ cd <project-name>

Next, add the Angular PWA (Service Worker) functionality:

# long form docker command
docker run --rm -it -v $(pwd):/app angular-util:10.2.0 ng add @angular/pwa --project <project-name>

# or, with Angular CLI installed on your machine, 
# or, with alias ng='docker run --rm -it -v $(pwd):/app angular-util:10.2.0 ng'
$ ng add @angular/pwa --project <project-name>

NOTE: If you are interested in learning more about the Docker Container that I'm using above (rather than installing the Angular CLI on your host machine), you can read my blog post about Docker Utility Containers.

Q?:  In the ng add command above, is --project <project-name> really required?

Performing this step to a newly created (default) Angular application results in the following files being modified and created.

$ git s
On branch master
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   angular.json
	modified:   package-lock.json
	modified:   package.json
	modified:   src/app/app.module.ts
	modified:   src/index.html

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	ngsw-config.json
	src/assets/icons/
	src/manifest.webmanifest

Using a Dockerized Angular environment, this newly created PWA can then be built and served using the following commands:

# using long form
$ docker run --rm -it -v $(pwd):/app angular-util:10.2.0 ng build --prod

# or, with Angular CLI installed on your machine, 
# or, using angular-cli specific alias
# with alias ng='docker run --rm -it -v $(pwd):/app angular-util:10.2.0 ng'
$ ng build --prod

# or, using generic angular-util image (NodeJS, Angular, npm, yarn, etc)
# with alias ngi='docker run --rm -it -v $(pwd):/app angular-util:10.2.0'
$ ngi ng build --prod

chunk {} runtime.acf0dec4155e77772545.js (runtime) 1.45 kB [entry] [rendered]
chunk {1} main.a2f2f2ba868f42fbe918.js (main) 225 kB [initial] [rendered]
chunk {2} polyfills.35a5ca1855eb057f016a.js (polyfills) 36 kB [initial] [rendered]
chunk {3} styles.09e2c710755c8867a460.css (styles) 0 bytes [initial] [rendered]
Date: 2020-11-22T22:50:56.978Z - Hash: 73ad25d26b84753bcc89 - Time: 22633ms

Finally, the PWA can be served via:

$ docker run --rm -it -v $(pwd)/dist/:/app -p 8080:8080 angular-util:10.2.0 npx http-server ./cli-spa/

Another important note about hosting PWAs is that they must be served over an HTTPS connection when deployed anywhere other than localhost!

• When using SSH as the protocol to interact with the Git repository, make sure you include the ".git" suffix as part of the URL specification to the "git remote add" command.  You can verify this by using git remote -v and look for .git suffix.  

$ git remote add origin git@gitlab.com:<namespace>/<repo>.git

$ git remote -v
origin	git@gitlab.com:<namespace>/testrepo.git (fetch)
origin	git@gitlab.com:<namespace>/testrepo.git (push)

• For a visual, pattern-matching rule of thumb, if the git remote URL starts with git, it needs to end with .git.  (Otherwise, it is an HTTP protocol and it should not end in .git)
• When setting the upstream connection for a branch, use "git push -u [--set-upstream]":

$ git push -u <remote-URL.git> <branch> # -- or 
$ git push --set-upstream <remote-URL.git> <branch>

# for example
$ git push -u git@gitlab.com:<namespace>/testrepo.git master

# or, rely on a remote alias (as "origin" set above)
$ git push -u origin master

• When using the command line, it's better to be explicit about which remote and what branch rather than rely on Git defaults for things like push, pull, etc

$ git push origin master

It's possible to do the following to create a new GitLab project from the command line:

$ mkdir testrepo
$ cd !$
$ git init
$ git remote add origin git@gitlab.com:<namespace>/<project>.git

... work, git add, git commit
$ git push -u origin master

# verify upstream branch is configured
$ git branch -vv
* master 96d323a [origin/master] :tada: fixed

# more validation of the repo config
$ more .git/config
[core]
	repositoryformatversion = 0
	filemode = true
	bare = false
	logallrefupdates = true
[remote "origin"]
	url = git@gitlab.com:<namespace>/testrepo.git
	fetch = +refs/heads/*:refs/remotes/origin/*
[branch "master"]
	remote = origin
	merge = refs/heads/master

Notes:

• By default the repo will be created in GtiLab as a "private" project.  This can be changed later.
• When using the HTTP protocol to interact with the Git Repo, you do NOT include the ".git" suffix as part of the <URL>.  But, when using SSH protocol you MUST include the ".git" suffix as part of the <URL>.  
• A lot of the git-scm documentation mixes the use of https vs ssh.  So, if you're not paying attention, you may miss this subtlety.

Questions:

• Can we set upstream repos/branches for each branch?  (I'm pretty sure we can, but I need to verify.)  

References:

• https://docs.gitlab.com/ee/gitlab-basics/create-project.html#push-to-create-a-new-project

What Max did for me was introduce the idea of a "utility container".  I then considered using them to be the primary tool to bootstrap a project such as "npm init" or "ng new project".

I then realized that this is very similar to what the AWS CLI team had produced with their Dockerized AWS CLI tool.  Their simple idea of using an Alias with their dockerized AWS CLI tool solidified what I had wanted to achieve all along, which was to be able to simply type: "npm init" from the command line and have a dockerized Node to run.

Before the Dockerized version of AWS CLI tool was available, installing the AWS CLI was a lengthy process of ensuring we met the pre-requisites, using "curl" to download the code, unzipping, running an install script which also installed Python because it is dependent on it.  Similarly, in order to update to a newer version, we had to uninstall, unlink software, etc, etc.  

Using Docker containers is so much cleaner to just about everything!

Prerequisites:

• Docker 19.03.13 (or newer) installed

"Installing" The Software:

• Consider, this new process to install an Angular development environment, e.g. Angular utility container.

FROM node:14.15.0

RUN npm install -g @angular/cli@10.2.0

USER node
WORKDIR /app
ENV PATH /app/node_modules/.bin:$PATH

$ build docker -t angular-util:10.2.0 . # don't forget the dot (.)

$ alias ng="docker run -it --rm -v ~/.gitconfig:/home/node/.gitconfig \
  -v $(pwd):/app angular-util:10.2.0 ng"
$ alias ts-node="docker run -it --rm -v $(pwd):/app  \
  angular-util:10.2.0 ts-node"
$ alias node="docker run -it --rm -v $(pwd):/app \
  angular-util:10.2.0 node"

Usage:

Create ("initialize", "bootstrap") a cool new Angular Project, without having Node and Angular installed on your bare metal system:

$ ng new <proejct name>
...
$ cd <project name>

Other examples:

$ node --version
v14.15.0
$ npm --version
6.14.8
$ yarn --version
1.22.5

Initialize a NodeJS backend:

$ mkdir backend
$ npm init
This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sensible defaults.

See `npm help init` for definitive documentation on these fields
and exactly what they do.

Use `npm install <pkg>` afterwards to install a package and
save it as a dependency in the package.json file.

Press ^C at any time to quit.
package name: (app) backend
version: (1.0.0) 
description: Testing docker
entry point: (index.js) 
test command: 
git repository: 
keywords: 
author: 
license: (ISC) 
About to write to /app/package.json:

{
  "name": "backend",
  "version": "1.0.0",
  "description": "Testing docker",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}


Is this OK? (yes)

$ ll
total 12
drwxr-xr-x 2 scott scott 4096 Nov  5 08:18 ./
drwxr-xr-x 3 scott scott 4096 Nov  5 08:18 ../
-rw-r--r-- 1 scott scott  217 Nov  5 08:17 package.json

Keep in mind that the intent of the use of this "Utility Container" is merely to Bootstrap the application.  It is not enough to containerize the application itself.  That should be done in a Dockerfile or Docker Compose yml file that resides within the application itself.  This separates the functions of the containers.

Benefits:

Notice that from this "installation", we get the following software (all containerized into a nice, neat little package that's not polluting our bare metal system):

• Node 14.15.0
• NPM (packaged with Node)
• Yarn (packaged with Node)
• Angular CLI 10.2.0 development environment
• TS-NODE (packaged with Angular CLI)
• (many others...)

Also note the other advantages:

• It's possible to quickly change to another Node or Angular version by simply changing out the :tag that's used
• Changing the version does not mean that an entirely new Node or Angular image needs to be downloaded because of magic of Docker image layers which are provided via a Union File System.  Only the differences between the versions of Node need to be downloaded, not an entirely new image.

"Using Union filesystems is super cool because they merge all the files for each image layer together and presents them as one single read-only directory at the union mount point. If there are duplicate files in different layers, the file on the higher level layer is what is displayed."

• As a best practice, it's best to take advantage of the Union File System capabilities (e.g. docker layers) if you can favor one base image for multiple environments.  For example, using Node:14.15.0 for both the Node and Angular environments rather than mixing base images like Node:14.15.0 for node (backend api development) and Node:12.0.0 for Angular.  Docker will still union what it can together to be efficient, but we can help it if we try to stick to something consistent.

Troubleshooting:

If you're on a Linux / Unix environment and you run into file ownership issues when you do things like "npm init" or "ng new <project>", here are some steps you can use to overcome them:

The problem is most likely related to your Linux User not having User and Group Ids of 1000:1000.  The Node team had to assume something when they built the image, so, that's what they went with.  But, your user is likely not 1000:1000 if you are one of several people logged into a Linux server, rather than being the one and only user on a personal Linux system.

The fix is pretty simple; just a couple of modifications to the Dockerfile and the Docker build command - everything else stays the same.

FROM node:14.15.0

RUN userdel -r node

ARG USER_ID

ARG GROUP_ID

RUN addgroup --gid $GROUP_ID user

RUN adduser --disabled-password --gecos '' --uid $USER_ID --gid $GROUP_ID user

USER user

WORKDIR /app

$ docker build -t node-util:cliuser --build-arg USER_ID=$(id -u) --build-arg GROUP_ID=$(id -g) .