From 6129f4b96ecffb870ae6fd401a7d7ce92fe4450f Mon Sep 17 00:00:00 2001 From: Chris Swan <478926+cpswan@users.noreply.github.com> Date: Wed, 10 Jan 2024 14:44:10 +0000 Subject: [PATCH] docs: Relocate decisions from operations repo --- ...-03-dart-naming-convention-for-releases.md | 47 +++++++++++ decisions/2023-07-dart-package-pinning.md | 78 +++++++++++++++++++ decisions/2023-07-github-issue-content.md | 35 +++++++++ 3 files changed, 160 insertions(+) create mode 100644 decisions/2023-03-dart-naming-convention-for-releases.md create mode 100644 decisions/2023-07-dart-package-pinning.md create mode 100644 decisions/2023-07-github-issue-content.md diff --git a/decisions/2023-03-dart-naming-convention-for-releases.md b/decisions/2023-03-dart-naming-convention-for-releases.md new file mode 100644 index 0000000..65a06b4 --- /dev/null +++ b/decisions/2023-03-dart-naming-convention-for-releases.md @@ -0,0 +1,47 @@ +# Dart naming convention for releases + +* **Status:** Agreed +* **Last Updated:** 2023-03 +* **Objective:** Define how we notate which platform and architecture a +release file is applicable to. + +## Context & Problem Statement + +We offer a number of command line tools (e.g. SSH No Ports) and as a +convenience to users the binaries for those tools are often added to a GitHub +release. + +Given a number of platforms (MacOS, Linux, Windows) and architectures (arm, +arm64, x64) there are multiple ways that the releases can be named. + +## Goal + +Have a consistent way of denoting which platform and architecture a given +binary (or package containing a binary) is intended for. + +## Summary + +Adopt the Dart convention (as used for +[SDK downloads](https://dart.dev/get-dart/archive)), which gives us: + +* macOS + * arm64 + * x64 +* Linux + * arm + * arm64 + * ia32 + * riscv64 + * x64 +* Windows + * arm64 + * ia32 + * x64 + +The release package would then be: + +`--.` + +e.g. a compressed tar file for at_activate for Linux on arm64: + +`at_activate-linux-arm64.tgz` diff --git a/decisions/2023-07-dart-package-pinning.md b/decisions/2023-07-dart-package-pinning.md new file mode 100644 index 0000000..f4c554c --- /dev/null +++ b/decisions/2023-07-dart-package-pinning.md @@ -0,0 +1,78 @@ +# Dart package pinning + +* **Status:** Agreed +* **Last Updated:** 2023-07 +* **Objective:** Define when we should pin dependencies in Dart pubspec.yaml + +## Context & Problem Statement + +We make extensive use of Dart, and dependencies from the Dart package +manager [pub.dev](https://pub.dev). + +We also publish packages to pub.dev + +Where possible we should have control of our dependencies by use of +dependency pinning (with automated updates using Dependabot). This +helps us achieve repeatable builds, and improve the score for our +[OpenSSF Scorecards](https://github.com/atsign-foundation/.github/blob/trunk/docs/OpenSSF_scorecards.md). + +## Goal + +Have a consistent approach to dependency pinning in our pubspec.yaml files. + +## Summary + +We need to take a different approach for packages we publish to pub.dev +versus other packages and apps: + +### Packages we publish to pub.dev + +To maximise [pub points](https://pub.dev/help/scoring) packages should +[support up-to-date dependencies](https://pub.dev/help/scoring#support-up-to-date-dependencies): + +* Works with the latest stable Dart SDK. +* Works with the latest stable Flutter SDK (if applicable). +* Works with the latest versions of all dependencies. + +Dart dependencies [best practices](https://dart.dev/tools/pub/dependencies#best-practices) +advocate: + +* Use caret syntax +* Depend on the latest stable package versions +* Test whenever you update package dependencies + +Thus, published packages shouldn't make use of pinned dependencies, but +rather use caret syntax: + +```yaml +dependencies: + path: ^1.3.0 + collection: ^1.1.0 + string_scanner: ^0.1.2 +``` + +### Applications and internal packages + +When we're not publishing to pub.dev we should pin dependencies: + +```yaml +dependencies: + path: 1.3.0 + collection: 1.1.0 + string_scanner: 0.1.2 +``` + +Dependabot can then be configured to raise Pull Requests for updated +dependencies: + +`.github/dependabot.yml` + +```yaml +version: 2 +enable-beta-ecosystems: true +updates: + - package-ecosystem: "pub" + directory: "/packages/package_name" + schedule: + interval: "daily" +``` diff --git a/decisions/2023-07-github-issue-content.md b/decisions/2023-07-github-issue-content.md new file mode 100644 index 0000000..e9c9b94 --- /dev/null +++ b/decisions/2023-07-github-issue-content.md @@ -0,0 +1,35 @@ +# GitHub Issue Content + +* **Status:** Agreed +* **Last Updated:** 2023-07 +* **Objective:** Have GitHub issues that don't rely on linked content + +## Context & Problem Statement + +Very often we will have created content in apps like Google Docs, and it +can seem convenient to link to that content. Unfortunately this means that +the GitHub Issue doesn't make sense on its own, and sends the reader on a +'treasure hunt' to find the full context. + +For people who aren't on the staff of Atsign they'll often not be able to +access linked resources due to authentication requirements. + +## Goals + +Have GitHub issues that make sense on their own, without having to explore +linked content. + +Enable contributors to our open source projects to see the full context +rather than having it hidden behind authentication. + +## Summary + +Content should be copied into issues wherenever it's of suitable size and +can be shared in the open. + +For verbose content it may make sense to provide a summary and a link to +the original source, or a summary and a copy in a gist (or other freely +available resource). + +If there are concerns about sharing proprietary data then think carefully +about where to open the issue in terms of public versus private repos.