aljaz/hacker-laws
1
1
Fork 0
mirror of https://github.com/dwmkerr/hacker-laws.git synced 2025-12-17 04:35:12 +01:00
Code Issues Packages Projects Releases Wiki Activity

build: testing new build

Browse Source
This commit is contained in:
Dave Kerr
2025-03-31 08:10:24 +01:00
parent d6a7d4eac3
commit c1c7f013e7
7 changed files with 150 additions and 131 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
.github/release-please-config.json vendored Normal file
View File

@@ -0,0 +1,18 @@
{
"release-type": "simple",
"bump-minor-pre-major": true,
"packages": {
".": {
"release-type": "simple",
"extra-files": [
{
"type": "generic",
"path": "README.md"
}
],
"changelog-path": ".github/CHANGELOG.md"
}
}
}

3
.github/release-please-manifest.json vendored Normal file
View File

@@ -0,0 +1,3 @@
{
".": "0.1.0"
}

49
.github/workflows/build-on-pull-request.yaml vendored
View File

@@ -2,52 +2,3 @@ name: "Validate Pull Request"
on:
pull_request:
jobs:
test-website-build:
runs-on: ubuntu-24.04
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Test Website Build
run: |
cd .github/website
make install
make build
cp -r build/. '../pages'
ls -al "../pages"
prepare-pdf:
runs-on: ubuntu-24.04
steps:
- name: Checkout
uses: actions/checkout@v4
# Set a descriptive version. For PRs it'll be the short sha.
- name: Set Version
id: set_version
run: echo ::set-output name=VERSION::$(git rev-parse --short HEAD)
# Prepare the content files.
- name: Prepare Content
run: ./scripts/prepare-markdown-for-ebook.sh ${{ steps.set_version.outputs.VERSION }}
# Create a PDF from the prepared markdown.
- name: Prepare PDF
uses: docker://pandoc/latex:2.9
with:
args: "-V toc-title:\"Table Of Contents\" --toc --pdf-engine=pdflatex --standalone --output hacker-laws.pdf hacker-laws.md"
# Publish the PDF and intermediate markdown as an artifact.
- name: Publish PDF Artifact
uses: actions/upload-artifact@master
with:
name: hacker-laws.pdf
path: hacker-laws.pdf
- name: Publish Intermediate Markdown Artifact
uses: actions/upload-artifact@master
with:
name: hacker-laws.md
path: hacker-laws.md

80
.github/workflows/cicd.yaml vendored Normal file
View File

@@ -0,0 +1,80 @@
name: CI/CD
on:
push:
branches: [main]
pull_request:
workflow_dispatch:
permissions:
contents: write
pull-requests: write
jobs:
test-website-build:
runs-on: ubuntu-24.04
steps:
- name: Checkout
uses: actions/checkout@v5
- name: Test Website Build
run: |
cd .github/website
make install
make build
cp -r build/. '../pages'
ls -al "../pages"
release:
needs: test-website-build
runs-on: ubuntu-24.04
outputs:
released: ${{ steps.release-please.outputs.release_created }}
tag: ${{ steps.release-please.outputs.tag_name }}
steps:
- uses: googleapis/release-please-action@v4
id: release-please
with:
manifest-file: .github/release-please-manifest.json
config-file: .github/release-please-config.json
release-pdf:
runs-on: ubuntu-24.04
needs: release
if: ${{ needs.release.outputs.released }}
steps:
- name: Checkout
uses: actions/checkout@v5
# Set a descriptive version. For PRs it'll be the short sha.
- name: Check Version
run: echo "${VERSION}"
env:
VERSION: ${{ needs.release.outputs.tag }}
# Set a descriptive version. For PRs it'll be the short sha.
- name: Prepare Markdown
run: |
# Set the env vars we use (version set for clarity).
export DATE=$(date +%F)
export VERSION="${VERSION}"
make prepare-markdown
env:
VERSION: ${{ needs.release.outputs.tag }}
# Create the PDF files.
- name: Create PDF
run: make create-pdf
# Publish the PDF and intermediate markdown as an artifact.
# - name: Publish PDF Artifact
# uses: actions/upload-artifact@3
# with:
# name: hacker-laws.pdf
# path: hacker-laws.pdf
- name: Attach assets to GitHub Release
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
gh release upload "${{ needs.release.outputs.tag }}" --clobber hacker-laws.pdf hacker-laws.md

72
README.md
View File

@@ -1,3 +1,10 @@
---
title: "Hacker Laws"
author: "Dave Kerr, github.com/dwmkerr/hacker-laws"
subtitle: "Laws, Theories, Principles, and Patterns that developers will find useful. ${VERSION}, ${DATE}."
version: ${VERSION}
---
<h1 align="center"><a href="https://hacker-laws.com" target="_blank">hacker-laws</a></h1>
<h4 align="center">🧠 Laws, Theories, Principles and Patterns for developers and technologists.</h4>
@@ -86,10 +93,6 @@
- [Online Resources](#online-resources)
- [PDF eBook](#pdf-ebook)
- [Podcast](#podcast)
- [Translations](#translations)
- [Related Projects](#related-projects)
- [Contributing](#contributing)
- [TODO](#todo)
<!-- vim-markdown-toc -->
@@ -97,7 +100,7 @@
There are lots of laws which people discuss when talking about development. This repository is a reference and overview of some of the most common ones. Please share and submit PRs!
❗: This repo contains an explanation of some laws, principles and patterns, but does not _advocate_ for any of them. Whether they should be applied will always be a matter of debate, and greatly dependent on what you are working on.
Warning: This repo contains an explanation of some laws, principles and patterns, but does not _advocate_ for any of them. Whether they should be applied will always be a matter of debate, and greatly dependent on what you are working on.
## Laws
@@ -142,7 +145,6 @@ The diagram below shows some examples of potential improvements in speed:
<img width="480px" alt="Diagram: Amdahl's Law" src="./images/amdahls_law.png" />
*(Image Reference: By Daniels219 at English Wikipedia, Creative Commons Attribution-Share Alike 3.0 Unported, https://en.wikipedia.org/wiki/File:AmdahlsLaw.svg)*
As can be seen, even a program which is 50% parallelisable will benefit very little beyond 10 processing units, whereas a program which is 95% parallelisable can still achieve significant speed improvements with over a thousand processing units.
@@ -275,7 +277,6 @@ As a person's understanding and experience in a domain grows, they may well enco
Real-world examples:
* [Apple vs. FBI: Why This Anti-Terror Hawk Switched Sides](https://fortune.com/2016/03/10/apple-fbi-lindsay-graham/) - In 2016 Senator Lindsey Graham changed his stance on Apple creating a 'backdoor' in their encryption of devices. Initially Graham had been critical of Apple challenging a request to create a 'backdoor', which he saw as necessary to investigate potential terrorist plots. However, by Graham's own admission, as he learned more about the technical complexity of the domain, he realised that he had assumed it to be far more simple than he had realised, and that such a backdoor could have serious negative consequences. This could potentially be considered an example of the Dunning-Kruger effect - a cyber-security expert would likely understand immediately how such a backdoor could be exploited, as they have deep understanding of the domain, a layperson might assume that phone security is more similar to _physical security_ where the practice of having a 'master key' for law enforcement is possible, but this analogy does not apply sufficiently well to describe modern encryption in cyber-security.
### Fitts' Law
@@ -285,7 +286,6 @@ Fitts' law predicts that the time required to move to a target area is a functio
<img width="300px" alt="Diagram: Fitts Law" src="./images/Fitts_Law.svg" />
*(Image Reference: By Foobar628 at English Wikipedia, Creative Commons Attribution-Share Alike 3.0 Unported, https://en.wikipedia.org/wiki/Fitts%27s_law#/media/File:Fitts_Law.svg)*
The consequences of this law dictate that when designing UX or UI, interactive elements should be as large as possible and the distance between the users attention area and interactive element should be as small as possible. This has consequences on design, such as grouping tasks that are commonly used with one another close.
@@ -357,7 +357,6 @@ In the equation below, `T` is the time to make a decision, `n` is the number of
![Hicks law](./images/hicks_law.svg)
*(Image Reference: Creative Commons Attribution-Share Alike 3.0 Unported, https://en.wikipedia.org/wiki/Hick%27s_law)*
This law only applies when the number of options is _ordered_, for example, alphabetically. This is implied in the base two logarithm - which implies the decision maker is essentially performing a _binary search_. If the options are not well ordered, experiments show the time taken is linear.
@@ -408,7 +407,6 @@ The Hype Cycle is a visual representation of the excitement and development of t
![The Hype Cycle](./images/gartner_hype_cycle.png)
*(Image Reference: By Jeremykemp at English Wikipedia, CC BY-SA 3.0, https://commons.wikimedia.org/w/index.php?curid=10547051)*
In short, this cycle suggests that there is typically a burst of excitement around new technology and its potential impact. Teams often jump into these technologies quickly, and sometimes find themselves disappointed with the results. This might be because the technology is not yet mature enough, or real-world applications are not yet fully realised. After a certain amount of time, the capabilities of the technology increase and practical opportunities to use it increase, and teams can finally become productive. Roy Amara's quote sums this up most succinctly - "We tend to overestimate the effect of a technology in the short run and underestimate in the long run".
@@ -423,7 +421,6 @@ In short, this cycle suggests that there is typically a burst of excitement arou
>
> (Hyrum Wright)
Hyrum's Law states that when you have a _large enough number of consumers_ of an API, all behaviours of the API (even those not defined as part of a public contract) will eventually come to be depended on by someone. A trivial example may be non-functional elements such as the response time of an API. A more subtle example might be consumers who are relying on applying a regex to an error message to determine the *type* of error of an API. Even if the public contract of the API states nothing about the contents of the message, indicating users should use an associated error code, _some_ users may use the message, and changing the message essentially breaks the API for those users.
See also:
@@ -550,7 +547,6 @@ Example:
In its original context, this Law was based on studies of bureaucracies. It may be pessimistically applied to software development initiatives, the theory being that teams will be inefficient until deadlines near, then rush to complete work by the deadline, thus making the actual deadline somewhat arbitrary.
If this law were combined with [Hofstadter's Law](#hofstadters-law), an even more pessimistic viewpoint is reached - work will expand to fill the time available for its completion and *still take longer than expected*.
See also:
@@ -564,7 +560,6 @@ See also:
>
> [(Donald Knuth)](https://twitter.com/realdonaldknuth?lang=en)
In Donald Knuth's paper [Structured Programming With Go To Statements](http://wiki.c2.com/?StructuredProgrammingWithGoToStatements), he wrote: "Programmers waste enormous amounts of time thinking about, or worrying about, the speed of noncritical parts of their programs, and these attempts at efficiency actually have a strong negative impact when debugging and maintenance are considered. We should forget about small efficiencies, say about 97% of the time: **premature optimization is the root of all evil**. Yet we should not pass up our opportunities in that critical 3%."
However, _Premature Optimization_ can be defined (in less loaded terms) as optimizing before we know that we need to.
@@ -652,7 +647,6 @@ Following this principal limits the scope of changes, making them easier and saf
This law states that abstractions, which are generally used in computing to simplify working with complicated systems, will in certain situations 'leak' elements of the underlying system, this making the abstraction behave in an unexpected way.
An example might be loading a file and reading its contents. The file system APIs are an _abstraction_ of the lower level kernel systems, which are themselves an abstraction over the physical processes relating to changing data on a magnetic platter (or flash memory for an SSD). In most cases, the abstraction of treating a file like a stream of binary data will work. However, for a magnetic drive, reading data sequentially will be *significantly* faster than random access (due to increased overhead of page faults), but for an SSD drive, this overhead will not be present. Underlying details will need to be understood to deal with this case (for example, database index files are structured to reduce the overhead of random access), the abstraction 'leaks' implementation details the developer may need to be aware of.
The example above can become more complex when _more_ abstractions are introduced. The Linux operating system allows files to be accessed over a network but represented locally as 'normal' files. This abstraction will 'leak' if there are network failures. If a developer treats these files as 'normal' files, without considering the fact that they may be subject to network latency and failures, the solutions will be buggy.
@@ -939,11 +933,6 @@ See Also:
This is an acronym, which refers to:
* S: [The Single Responsibility Principle](#the-single-responsibility-principle)
* O: [The Open/Closed Principle](#the-openclosed-principle)
* L: [The Liskov Substitution Principle](#the-liskov-substitution-principle)
* I: [The Interface Segregation Principle](#the-interface-segregation-principle)
* D: [The Dependency Inversion Principle](#the-dependency-inversion-principle)
These are key principles in [Object-Oriented Programming](#todo). Design principles such as these should be able to aid developers build more maintainable systems.
@@ -1068,7 +1057,6 @@ See also:
[YAGNI on Wikipedia](https://en.wikipedia.org/wiki/You_ain%27t_gonna_need_it)
This is an acronym for _**Y**ou **A**in't **G**onna **N**eed **I**t_.
> Always implement things when you actually need them, never when you just foresee that you need them.
>
@@ -1155,47 +1143,3 @@ Hacker Laws has been featured in [The Changelog](https://changelog.com/podcast/4
<a href="https://changelog.com/podcast/403" target="_blank"><img src="./images/changelog-podcast.png" width="800px" alt="Changelog Podcast Image" /></a>
## Translations
Thanks to a number of wonderful contributors, Hacker Laws is available in a number of languages. Please consider sponsoring moderators!
| Language | Moderator | Status |
|----------|-----------|--------|
| [AR Arabic / Arabic](./translations/ar-AR.md) | [Abdurrahman Rajab - a0m0rajab](https://github.com/a0m0rajab) | . |
| [🇮🇩 Bahasa Indonesia / Indonesian](./translations/pt-BR.md) | [arywidiantara](https://github.com/arywidiantara) | [![gitlocalized ](https://gitlocalize.com/repo/2513/id/badge.svg)](https://gitlocalize.com/repo/2513/id?utm_source=badge) |
| [🇧🇷 Brasileiro / Brazilian](./translations/pt-BR.md) | [Eugênio Moreira](https://github.com/eugenioamn), [Leonardo Costa](https://github.com/leofc97) | [![gitlocalized ](https://gitlocalize.com/repo/2513/pt-BR/badge.svg)](https://gitlocalize.com/repo/2513/pt-BR?utm_source=badge) |
| [🇨🇳 中文 / Chinese](https://github.com/nusr/hacker-laws-zh) | [Steve Xu](https://github.com/nusr) | Partially complete |
| [🇩🇪 Deutsch / German](./translations/de.md) | [Vikto](https://github.com/viktodergunov) | [![gitlocalized ](https://gitlocalize.com/repo/2513/de/badge.svg)](https://gitlocalize.com/repo/2513/de?utm_source=badge) |
| [🇫🇷 Français / French](./translations/fr.md) | [Kevin Bockelandt](https://github.com/KevinBockelandt) | [![gitlocalized ](https://gitlocalize.com/repo/2513/fr/badge.svg)](https://gitlocalize.com/repo/2513/fr?utm_source=badge) |
| [🇬🇷 ελληνικά / Greek](./translations/el.md) | [Panagiotis Gourgaris](https://github.com/0gap) | [![gitlocalized ](https://gitlocalize.com/repo/2513/el/badge.svg)](https://gitlocalize.com/repo/2513/el?utm_source=badge) |
| [🇮🇹 Italiano / Italian](https://github.com/csparpa/hacker-laws-it) | [Claudio Sparpaglione](https://github.com/csparpa) | Partially complete |
| [🇯🇵 JP 日本語 / Japanese](./translations/jp.md) | [Fumikazu Fujiwara](https://github.com/freddiefujiwara)| [![gitlocalized ](https://gitlocalize.com/repo/2513/ja/badge.svg)](https://gitlocalize.com/repo/2513/ja?utm_source=badge) |
| [🇰🇷 한국어 / Korean](https://github.com/codeanddonuts/hacker-laws-kr) | [Doughnut](https://github.com/codeanddonuts) | Partially complete |
| [🇱🇻 Latviešu Valoda / Latvian](./translations/lv.md) | [Arturs Jansons](https://github.com/iegik) | [![gitlocalized ](https://gitlocalize.com/repo/2513/lv/badge.svg)](https://gitlocalize.com/repo/2513/lv?utm_source=badge) |
| [🇮🇷 فارسی / Persian](./translations/fa.md) | [MohammadErfan Gooneh](https://github.com/MEgooneh) | . |
| [🇵🇱 Polski / Polish](./translations/pl.md) | [Mariusz Kogen](https://github.com/k0gen) | [![gitlocalized ](https://gitlocalize.com/repo/2513/pl/badge.svg)](https://gitlocalize.com/repo/2513/pl?utm_source=badge) |
| [🇷🇺 Русская версия / Russian](https://github.com/solarrust/hacker-laws) | [Alena Batitskaya](https://github.com/solarrust) | Partially complete |
| [🇪🇸 Castellano / Spanish](./translations/es-ES.md) | [Manuel Rubio](https://github.com/manuel-rubio) ([Sponsor](https://github.com/sponsors/manuel-rubio)) | Partially complete |
| [🇹🇷 Türkçe / Turkish](https://github.com/umutphp/hacker-laws-tr) | [Umut Işık](https://github.com/umutphp) | [![gitlocalized ](https://gitlocalize.com/repo/2513/tr/badge.svg)](https://gitlocalize.com/repo/2513/tr?utm_source=badge) |
| [🇺🇦 українська мова / Ukrainian](./translations/uk.md) | [Nazar](https://github.com/troyane), [Helga Lastivka](https://github.com/HelgaLastivka) | [![gitlocalized ](https://gitlocalize.com/repo/2513/uk/badge.svg)](https://gitlocalize.com/repo/2513/uk?utm_source=badge) |
| [🇻🇳 Tiếng Việt / Vietnamese](./translations/vu.md) | [Nguyên](https://github.com/truonghoangnguyen), [Trương Hoàng](https://github.com/truonghoangnguyen) | [![gitlocalized ](https://gitlocalize.com/repo/2513/vi/badge.svg)](https://gitlocalize.com/repo/2513/vi?utm_source=badge) |
If you would like to update a translation, follow the [Translators Contributor Guide](https://github.com/dwmkerr/hacker-laws/blob/main/.github/contributing.md#translations).
## Related Projects
- [Tip of the Day](https://tips.darekkay.com/html/hacker-laws-en.html) - Receive a daily hacker law/principle.
- [Hacker Laws CLI](https://github.com/umutphp/hacker-laws-cli) - List, view and see random laws from the terminal!
- [Hacker Laws Action](https://github.com/marketplace/actions/hacker-laws-action) - Adds a random Hacker Law to a pull request as a small gift for the contributor, thanks [Umut Işık](https://github.com/umutphp)
## Contributing
Please do contribute! [Raise an issue](https://github.com/dwmkerr/hacker-laws/issues/new) if you'd like to suggest an addition or change, or [Open a pull request](https://github.com/dwmkerr/hacker-laws/compare) to propose your own changes.
Please be sure to read the [Contributing Guidelines](./.github/contributing.md) for requirements on text, style and so on. Please be aware of the [Code of Conduct](./.github/CODE_OF_CONDUCT.md) when engaging in discussions on the project.
## TODO
Hi! If you land here, you've clicked on a link to a topic I've not written up yet, sorry about this - this is work in progress!
Feel free to [Raise an Issue](https://github.com/dwmkerr/hacker-laws/issues) requesting more details, or [Open a Pull Request](https://github.com/dwmkerr/hacker-laws/pulls) to submit your proposed definition of the topic.

22
makefile Normal file
View File

@@ -0,0 +1,22 @@
default: help
.PHONY: help
help: # Show help for each of the Makefile recipes.
@grep -E '^[a-zA-Z0-9 -]+:.*#' Makefile | sort | while read -r l; do printf "\033[1;32m$$(echo $$l | cut -f 1 -d':')\033[00m:$$(echo $$l | cut -f 2- -d'#')\n"; done
.PHONY: prepare-markdown
prepare-markdown: # Prepare the markdown for PDF output.
./scripts/prepare-markdown-for-ebook.sh "README.md" "hacker-laws.md"
.PHONY: create-pdf
create-pdf: # Create the PDF.
docker run --rm \
--platform linux/amd64 \
-v ${PWD}:/data \
pandoc/latex:3.6 \
-V toc-title:"Table Of Contents" \
--toc \
--pdf-engine=lualatex \
--standalone \
--output hacker-laws.pdf \
hacker-laws.md

37
scripts/prepare-markdown-for-ebook.sh
View File

@@ -1,32 +1,33 @@
#!/usr/bin/env bash
# This script prepares a `hacker-laws.md` file for export to PDF or e-book format.
# Require a version number and get the current date.
version=$1
date=$(date "+%Y-%m-%d")
# Fail on errors.
set -e -o pipefail
if [ -z "$version" ]; then
echo "Usage: $0 <version>"
# Check if parameters are provided
input="$1"
output="$2"
if [ -z "${input}" ] || [ -z "${output}" ]; then
echo "usage: $(basename "$0") <input> <output>" >&2
echo " input: source markdown file (usually README.md)" >&2
echo " output: output markdown file (usually hacker-laws.md)" >&2
exit 1
fi
# Create `hacker-laws.md` with frontmatter and README content in one step.
cat << EOF > hacker-laws.md
---
title: "Hacker Laws"
author: "Dave Kerr, github.com/dwmkerr/hacker-laws"
subtitle: "Laws, Theories, Principles, and Patterns that developers will find useful. ${version}, ${date}."
---
# Grab env vars used to configure output, fail if required are missing.
export date="${DATE:-$(date +%F)}"
export version="${VERSION?error: VERSION must be set}"
EOF
cat README.md >> hacker-laws.md
# Update the input file to an intermedate.
intermediate="${input}.temp"
DATE="${date}" VERSION="${version}" envsubst < "${input}" > "${intermediate}"
# Use a single `sed` command to clean up unwanted lines and emojis in one pass.
sed -i'' -e '/💻📖.*/d' \
sed -e '/💻📖.*/d' \
-e 's/❗/Warning/g' \
-e '/^\[Translations.*/d' \
-e '/\*.*/d' \
-e '/ \*.*/d' \
-e '/## Translations/,$d' hacker-laws.md
-e '/## Translations/,$d' "${intermediate}" > "${output}"
rm "${intermediate}"
echo "hacker-laws.md prepared successfully."
echo "${output} prepared successfully."