Merge pull request #124 from atsign-foundation/cpswan-move-decisions

docs: Relocate decisions from operations repo

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:
+
+`<packagename>-<platform>-<architecture>.<format>`
+
+e.g. a compressed tar file for at_activate for Linux on arm64:
+
+`at_activate-linux-arm64.tgz`

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"
+```

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.