yplatform

yplatform supports various cycles of software development, through a canonical set of commands.

yplatform aims to diminish cognitive load 💆, time to first build ⏱️ and time to first deployment 🚀 . Why?

This was conceived within Tobii Pro's Cloud Services team 👋 .

---

git clone git://github.com/ysoftwareab/yplatform.git and you will gain access to:

• a bootstrap process for local-development based on GNU and Homebrew
  • [cross-platform](#cross-platform].
    • No more worries about this is how it works on a developer machine (e.g. MacOS/Windows) and this is how it works in the CI (e.g. Linux).
  • brings common GNU utilities (bash, make, grep, sed, find, etc), version locked.
    • No more worries about different flags, different behaviour or missing features!
  • brings Homebrew.
    • No more worries about different versions available in distros' repositositories, or libraries/utilities not being available at all.
• sane per-user configuration e.g. git
• various utility scripts, 99% GNU Bourne Again Shell (Bash)
• documentation and best common practices

---

Use yplatform in a project and you will gain access to:

• a bootstrap process for CI machines based on GNU and Homebrew
  • cross-provider. No more worries about running pipelines with multiple CI providers, or switching to a new CI provider.
• a build system based on GNU Make, both robust and flexible
• sane per-repo configurations e.g. vscode
• various utility scripts, 99% Bourne Again Shell (Bash)
• a cloud infrastructure-as-code system based on GNU Make, both robust and flexible

---

Show me!

TODO

---

Cross-platform

Similarly yplatform itself runs across these platforms with very little effort and no duplication. Bootstrapped Docker images are also available.

Platform	minimal	common	minimal (Docker)	common (Docker)
Apple MacOS	✔️	✔️
Linux (Alpine)	✔️	✔️	yp-alpine-3.11.7-minimal	yp-alpine-3.11.7-common
Linux (Archlinux)	✔️	✔️	yp-arch-0-minimal	yp-arch-0-common
Linux (Centos)	✔️	✔️	yp-centos-8-minimal	yp-centos-8-common
Linux (Debian 9)	✔️	✔️	yp-debian-9-minimal	yp-debian-9-common
Linux (Debian 10)	✔️	✔️	yp-debian-10-minimal	yp-debian-10-common
Linux (Ubuntu 16.04)	✔️	✔️	yp-ubuntu-16.04-minimal	yp-ubuntu-16.04-minimal
Linux (Ubuntu 18.04)	✔️	✔️	yp-ubuntu-18.04-minimal	yp-ubuntu-18.04-minimal
Linux (Ubuntu 20.04)	✔️	✔️	yp-ubuntu-20.04-minimal	yp-ubuntu-20.04-minimal
Microsoft Windows (WSL)	✔️	💤

NOTE common install is paused for Microsoft Windows (WSL) because the process takes more than 1 hour on Github Actions CI (a combination of machine specs and being restricted to WSL v1), but we expect no problems.

NOTE it should even possible to create WSL images. Tracked in #213.

---

Cross-provider

yplatform itself currently runs across these providers with very little effort and no duplication.

Provider	yplatform status	master	provider-branches	version tags	PR	config
AppVeyor		✔️	appveyor*			config
Bitrise		💤	bitrise*			config
Buddy		✔️	buddy*			config
CircleCI		✔️	circle*	✔️	✔️	config
Cirrus CI		✔️	cirrus*		✔️	config
Codeship		✔️	codeship*			config
Github Actions CI		✔️	github*	✔️	✔️	config
Gitlab CI		✔️	gitlab*			config
Semaphore		✔️	semaphore*		✔️	config
Sourcehut		✔️	sourcehut*		✔️	config
Travis CI		💤	travis*			config

NOTE Bitrise builds for the master branch are paused because the freemium includes only 500 credits (so 500 minutes on Linux agents).

NOTE Travis CI builds for the master branch are paused because one has to constantly ask for more open-source credits.

• Integration with Travis CI is unstable since it now requires a subscription.
• The new pricing model for travis-ci.com
• Travis CI's new pricing plan threw a wrench in my open source works
• Travis CI is no longer providing CI minutes for open source projects

---

Structure

• /mk has common include makefiles e.g. sourced from /build.mk makefiles
• /sh has common include shell scripts e.g. sourced from /bin shell scripts
• /bin has executable scripts, 99% GNU Bourne Again Shell (Bash)
• /bootstrap has scripts that help bootstrap a machine
• /ci has scripts that help steer the CI pipelines
• /dev has scripts that help bootstrap a developer machine
• /dockerfiles has scripts for the bootstrapped Docker images
• /gitconfig has git configuration
• /repo has configuration that is repo-specific, for those repositories bootstrapped with yplatform

---

Why?

yplatform aims to diminish cognitive load 💆, time to first build ⏱️ and time to first deployment 🚀 .

This means removing out-of-band information about system dependencies. How many times a repository's README mentions "something version x required"? How many times it doesn't mention, and you check the CI/Dockerfile?

This means removing differences in installing system dependencies. How many times did you look up "how to install X on Y?" How many times did you discover that you get different system dependencies, depending on the version of your Linux distribution?

This means removing differences in core utilities. How many times do you get something working on your MacOS development machine (BSD), only to see it fail on a CI machine, say running Ubuntu (GNU)?

This means removing differences in installing local dependencies. How many times a repository's README mentions npm install or yarn install or pip install or ./configure --prefix=/usr; make?

This means removing differences in triggering a build, checks, tests, a deployment, etc between codebases and their main programming language. How many times did you check how to build a codebase, what language it is using, what package manager or test framework it is using, what services need to be up, etc? How many times did you realize that checks are impossible to run locally, and that they run only in the CI, or worse - as a service reviewing/commenting your PR? How many times did you return years after to an old codebase, of your own above all!, only to realize you have no clue what's needed to build it again?

This means removing differences between what runs locally and what runs in the CI. How many times did you realize that you're instrumenting the CI ever-so-slightly-different than your local runs? Because maybe you duplicated code in the scripts section of your package.json and your GitHub workflow YAML?

This means removing differences between CI providers. How many times did you postpone trying out another CI provider? How many times did you choose a provider based on previous experience, popularity, how easy it is to integrate, rather than based on whether it is the most appropriate for the job at hand?

This means consolidating best current practices. How many times did you look up how to set up encryption in a git repository? How many times

This means trying to make everything work the same everywhere. Emphasis on trying. In reality, 100% the same is not possible. But it is possible to achieve say 80%. And 80% is much better than 0% i.e. not trying at all.

---

Documentation

• newcomer
  • bootstrap
• daily work
  • git (and Github) Pull Requests
  • working with make
  • working with a local npm dependency
  • how to release
  • style
    • Use common sense and BE CONSISTENT. (Google)
    • Less than 120 cpl, preferably less than 80
    • shell
    • Makefile
    • JavaScript/TypeScript
    • SASS
• set up a new git repository
  • new git (and Github) repositories
  • how to license
  • integrate Travis CI
  • .ci.sh
  • how to manage secrets
• Amazon Web Services
  • CloudFormation
  • Identity Access Management

---

Writing

• https://developers.google.com/tech-writing/overview
• https://github.com/google/styleguide/blob/gh-pages/docguide/philosophy.md
• https://www.julian.com/guide/write/intro

---

License

Apache-2.0