wiki experiment (#76)

Author: devoncarew

docs/Bug-Bankruptcy.md

@@ -0,0 +1,20 @@
+## What's this?
+
+When triaging repos we periodically decide that some portion of the open issues are older,
+may be stale, or may no longer be relevant for the current goals of the project. In order
+for use to be able to effectively use our issues trackers, we may choose to close this
+category of issues as `closed-bug-bankruptcy`.
+
+This is not intended as a commentary of the
+quality of the report, but part of our regular process to maintain good hygiene and utility
+of our issue trackers.
+
+## I think a closed issue is still relevant
+
+If you think an issue was closed in error, please:
+
+- comment to that effect on the issue, or
+- re-open the issue, or
+- open a new issue (esp. if the original issue may not fully apply anymore)
+
+We do expect some (smaller) portion of issues closed via a bug bankruptcy to later re-open.

docs/Changelog.md

@@ -0,0 +1,7 @@
+Changes to any package should be noted in their `CHANGELOG.md` file.
+
+As a rule of thumb, it is advised to add an entry for changes to 
+
+* files in the `bin/` or 'lib/' directory,
+* the `pubspec.yaml`,
+* the `README.md`.

docs/Home.md

@@ -0,0 +1 @@
+Welcome to the ecosystem wiki!

docs/License-Header.md

@@ -0,0 +1,14 @@
+All source files should start with this license header:
+
+```
+// Copyright (c) 2023, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+```
+
+It can be added either manually or by running the following in your repository directory:
+
+```bash
+dart pub global activate --source git https://github.com/mosuem/file_licenser
+dart pub global run file_licenser .
+```

docs/Merging-existing-repos-into-a-monorepo.md

@@ -0,0 +1 @@
+For instructions on how to merge an existing repository into a monorepo, see https://github.com/dart-lang/tools/pull/100.

docs/Publishing-automation.md

@@ -0,0 +1,56 @@
+## Contributions, PRs, and publishing
+
+When contributing to packages that use our publishing validation and automation bot:
+
+- if the package version is a stable semver version (`x.y.z`), the latest
+  changes have been published to pub. Please add a new changelog section for
+  your change, rev the service portion of the version, append `-dev`, and update
+  the pubspec version to agree with the new version
+- if the package version ends in `-dev`, the latest changes are unpublished;
+  please add a new changelog entry for your change in the most recent section.
+  When we decide to publish the latest changes we'll drop the `-dev` suffix
+  from the package version
+- for PRs, the `Publish` bot will perform basic validation of the info in the
+  pubspec.yaml and CHANGELOG.md files
+- when the PR is merged into the main branch, if the change includes reving to
+  a new stable version, a repo maintainer will tag that commit with the pubspec
+  version (e.g., `v1.2.3`); that tag event will trigger the `Publish` bot to
+  publish a new version of the package to pub.dev
+
+If the `dart pub publish --dry-run` step is failing during PR validation, and
+it's for a reason that could legitimately be ignored (publishing using a
+pre-release SDK?), repo committers can add the `publish-ignore-warnings` label
+to the PR in order to ignore failures from a publishing dry-run. 
+
+## More publishing conventions
+
+For more information on dart-lang package publishing and maintenance conventions,
+see https://github.com/dart-lang/sdk/wiki/External-Package-Maintenance.
+
+## For committers: publishing a release
+
+> TLDR: After merging a PR, create a new GitHub release to publish it. This is best done
+using the link that firehose creates in the 'Package publishing' comment.
+
+Once a new release is ready to go - the latest bits have landed in the default branch -
+it can be published by tagging the commit with a well-formed tag. Generally this is in
+the form of `package_name-v1.2.3`; the publishing automation will indicate the correct
+tag to use in the PR.
+
+There are two ways to do this. One is by tagging the commit via the command line and
+pushing the new tag to the repo. That's correct, but there's a better way.
+
+The 2nd way to publish is by creating a github release (see the `/releases` url of your
+repo; e.g., https://github.com/dart-lang/tools/releases). Creating a new release there
+will tag the commit as a by-product, which will trigger a release. To create a release:
+
+- go to the `https://github.com/<org>/<repo>/releases` url
+- click 'draft a new release'
+- in 'choose tag', enter the tag of the correct publishing tag (you'll be creating a new tag)
+- in 'release title', enter the same text as the tag (by convention; this area is free-form)
+- in 'describe this release', enter the portion of the changelog entry for this release
+
+Firehose will create a hyperlink in it's comment on the PR with all the release information
+filled out. After the PR is merged - and we're ready to publish - it is highly recommended to
+use this link to create the release (instead of manually filling in the information). This
+helps make our releases more standardized and less error-prone.

docs/Pull-Request-Health.md

@@ -0,0 +1,19 @@
+To help developers and reviewers with creating PRs, we provide a Github CI action to do some simple checks. At the moment, we are checking for
+
+* License headers
+* Changelog entry
+.
+
+The workflow can be used by inserting the following into a `.github/workflows/health.yaml` file in your repository:
+```
+name: Health
+on:
+  pull_request:
+    branches: [ main ]
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+jobs:
+  health:
+    uses: dart-lang/ecosystem/.github/workflows/health.yaml@main
+#   with:
+#     checks: "version,changelog,license" 
+```

docs/Renaming-master-branches-to-main.md

@@ -0,0 +1,26 @@
+Many of our repos currently use `master` as the name of the default branch; over time we'd like to have them instead use `main` as the name of the default branch.
+
+### Renaming master to main
+
+The work per-repo is fairly modest. For people who want to take this on, here are the steps:
+
+- pre-announce the move (as a GitHub issue or as a communication to the active user group)
+- use the rename branch feature to rename `master` to `main`; this is available from the `<org>/<repo>/branches` page. If you do not have rights to rename the `master` branch, ping @devoncarew or @athomas
+- update references to the old branch name (generally in the `.github/workflows` workflow files)
+- for google3, in `third_party/dart/<packageName>/copy.bara.sky`, update the name of the branch that we sync to (`branch = "main"`)
+- message to users that the change was made and how to update any local checkouts
+
+GitHub's doc for this are here: [renaming a branch](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/renaming-a-branch). In-lined from there: "when you rename a branch on GitHub.com, any URLs that contain the old branch name are automatically redirected to the equivalent URL for the renamed branch. Branch protection policies are also updated, as well as the base branch for open pull requests (including those for forks) and draft releases."
+
+### Updating a local checkout
+
+After a rename, people with local checkouts will need to run:
+
+```
+git branch -m master main
+git fetch origin
+git branch -u origin/main main
+git remote set-head origin -a
+```
+
+The GitHub UI will prompt users with the above steps the next time they visit the repo page.

docs/Test-Coverage.md

@@ -0,0 +1 @@
+Test coverage should not decrease by introducing a PR. An exception are files in `/bin`, which are generally not tested, and should be kept relatively free of logic for that reason.