lihu/cleanup

.github/CODEOWNERS

@@ -0,0 +1,11 @@
+* @broadinstitute/devnull
+
+# Add your team as codeowners to files you own so that you can modify them
+# without BITS approval. List your workflows explicitly; do not use wildcards
+# here. BITS should proofread new templates before they are visible to the
+# entire organization. After that, maintenance is self-serve.
+#
+# The codeowner should be a group, not an individual user, to ensure continuity
+# of maintenance through personnel turnover.
+/.github/workflow-templates/bits-example.yml             @broadinstitute/devnull
+/.github/workflow-templates/bits-example.properties.json @broadinstitute/devnull

.github/workflow-templates/bits-example.properties.json

@@ -0,0 +1,8 @@
+{
+    "name": "BITS example workflow template",
+    "description": "Print a custom cowsay message. No production use.",
+    "categories": [
+        "testing"
+    ],
+    "labels": ["preview"]
+}

.github/workflow-templates/bits-example.yml

@@ -0,0 +1,21 @@
+---
+# A trivial Github workflow template
+# Prints a cowsay message based on a file that exists in the repo
+# Requires `.cowsay.txt` to exist in the project root.
+name: "Example workflow template"
+
+"on":
+  pull_request:
+    branches:
+      - "$default-branch"
+
+jobs:
+  cowsay:
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: "Check out repo"
+        uses: "actions/checkout@v4"
+      - name: "Install cowsay"
+        run: "sudo apt-get install cowsay"
+      - name: "Print a repo-specific cowsay message"
+        run: "/usr/games/cowsay <.cowsay.txt"

.github/workflows/workflow-templates.yaml

@@ -0,0 +1,31 @@
+---
+name: "Validate workflow templates"
+
+"on":
+  pull_request:
+    branches:
+      - "main"
+
+jobs:
+  lint:
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: "Checkout repo"
+        uses: "actions/checkout@v4"
+      - name: "Smoke check metadata files"
+        run: >-
+          cat .github/workflow-templates/*.json | jq > /dev/null
+      - name: "Lint template files"
+        run: >-
+          yamllint -s .github/workflow-templates/*.yml
+      - name: "Ensure '.yml' file extension"
+        run: >-
+          [[ -z "$(find .github/workflow-templates/ -maxdepth 1 -name "*.yaml")" ]]
+        # Any namespaced filename will have at least one '-'. Kebab case should
+        # have no underscores or capital letters.
+      - name: "Check for kebab case/namespacing"
+        run: >-
+          [[ -z "$(find .github/workflow-templates -maxdepth 1 -regextype egrep -regex '^.*/[^-]*$|^.*[_A-Z].*$')" ]]
+      - name: "Ensure all templates are in CODEOWNERS"
+        run: >-
+          for filename in .github/workflow-templates/*; do grep "/${filename}" ./.github/CODEOWNERS; done

.yamllint.yaml

@@ -0,0 +1,13 @@
+---
+extends: "default"
+
+rules:
+  braces:
+    forbid: true
+  brackets:
+    forbid: true
+  indentation:
+    spaces: 2
+  quoted-strings:
+    required: true
+    quote-type: "double"

CODE_OF_CONDUCT.md

@@ -2,76 +2,83 @@
 
 ## Our Pledge
 
-In the interest of fostering an open and welcoming environment, we as
-contributors and maintainers pledge to making participation in our project and
-our community a harassment-free experience for everyone, regardless of age, body
-size, disability, ethnicity, sex characteristics, gender identity and expression,
-level of experience, education, socio-economic status, nationality, personal
-appearance, race, religion, or sexual identity and orientation.
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
 
 ## Our Standards
 
-Examples of behavior that contributes to creating a positive environment
-include:
+Examples of behavior that contributes to a positive environment for our
+community include:
 
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
 
-Examples of unacceptable behavior by participants include:
+Examples of unacceptable behavior include:
 
-* The use of sexualized language or imagery and unwelcome sexual attention or
- advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
 * Public or private harassment
-* Publishing others' private information, such as a physical or electronic
- address, without explicit permission
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
 * Other conduct which could reasonably be considered inappropriate in a
- professional setting
+  professional setting
 
-## Our Responsibilities
+## Enforcement Responsibilities
 
-Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
 
-Project maintainers have the right and responsibility to remove, edit, or
-reject comments, commits, code, wiki edits, issues, and other contributions
-that are not aligned to this Code of Conduct, or to ban temporarily or
-permanently any contributor for other behaviors that they deem inappropriate,
-threatening, offensive, or harmful.
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
 
 ## Scope
 
-This Code of Conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community. Examples of
-representing a project or community include using an official project e-mail
-address, posting via an official social media account, or acting as an appointed
-representative at an online or offline event. Representation of a project may be
-further defined and clarified by project maintainers.
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
 
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting http://broad.io/EthicsReporting or any project 
-team member with whom you feel comfortable communicating. All
-complaints will be reviewed and investigated and will result in a response that
-is deemed necessary and appropriate to the circumstances. The project team is
-obligated to maintain confidentiality with regard to the reporter of an incident.
-Further details of specific enforcement policies may be posted separately.
+reported through [official Broad channels.](https://www.broadinstitute.org/contact#report)
 
-Project maintainers who do not follow or enforce the Code of Conduct in good
-faith may face temporary or permanent repercussions as determined by other
-members of the project's leadership.
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
 
-[homepage]: https://www.contributor-covenant.org
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
 
-For answers to common questions about this code of conduct, see
-https://www.contributor-covenant.org/faq
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

catalog-info.yaml

@@ -0,0 +1,18 @@
+---
+apiVersion: "backstage.io/v1alpha1"
+kind: "Component"
+metadata:
+  name: "dot-github"
+  title: "Broad Institute default files"
+  description: >-
+    Files defined here either propogate or define certain behavior in all
+    broadinstitute repostiories.
+  tags:
+    - "github"
+  annotations:
+    github.com/project-slug: "broadinstitute/.github"
+    backstage.io/techdocs-ref: "dir:."
+spec:
+  type: "library"
+  owner: "devnull"
+  lifecycle: "production"

docs/README.md

@@ -0,0 +1,81 @@
+# Broad Institute default files
+
+Files defined here either propogate or define certain default behavior in all
+broadinstitute repositories. See
+[the .github documentation](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file)
+for more information.
+
+## Contribution guidelines
+
+Currently, the only feature we are taking community contributions for is
+[workflow templates.](https://docs.github.com/en/actions/sharing-automations/creating-workflow-templates-for-your-organization)
+We are open to supporting other `.github` features though -- please contact the
+devnull team in #github or #team-devnull if there is something you believe the
+organization would benefit from.
+
+### Commit guidelines
+
+All commits should follow these abridged standard formatting rules:
+
+* Separate subject from body with a blank line
+* Limit the subject line to 50 characters
+* Capitalize the subject line
+* Do not end the subject line with a period
+* Use the imperative mood in the subject line
+* Wrap the body at 72 characters
+* Use the body to explain what and why vs. how
+  *This is the most important rule by far!*
+
+For an in-depth explanation about where these are from and why they're
+important, see
+[this excellent blog post on Git hygiene.](https://cbea.ms/git-commit/)
+These rules are a subset of the patch submission guidelines used
+[on the git project itself.](https://github.com/git/git/blob/master/Documentation/SubmittingPatches)
+Since they are so common, most text editors will help you out with
+automatic formatting and syntax highlighting with minimal configuration.
+
+### Adding a workflow template
+
+We encourage any Broadie to submit a PR to make their template available to the
+entire organization if they so choose. When you do, we ask that you follow the
+following instructions. In addition to keeping the repo organized, our goal with
+these standards is to avoid any workflow appearing prescriptive. Since these
+templates are visible to the entire organization, users browsing them should
+have clear information about their provenance and be able to choose tools that
+fit their needs.
+
+#### Naming conventions
+
+* Namespace your workflows by prefixing the files with your team
+  name. e.g. `bits-python-ci.yml`, instead of `python-ci.yml`.
+* Use `.yml` as a file extension, not `.yaml`.
+* Use `kebab-case` for all file names.
+* Have the file name be reasonably
+  descriptive. e.g. `bits-markdown-linting.yml`, not `bits-toolbox.yml`.
+
+#### The whole Broad is your audience
+
+When adding a new workflow, keep in mind that it will be visible to all Github
+users at the Broad Institute. Most will not know you or be familiar with your
+team's tech stack. At the same time, BITS believes that sharing technology at
+the Broad benefits everyone and that we should facilitate reuse of common
+patterns. To the extent possible, try to make your workflow generalizable:
+
+* Avoid hardcoding your team name in the workflow or referencing nonstandard
+  resources without explanation.
+* Use comments in the workflow file to document parts that may not be clear
+  without context.
+* The metadata file should include your team's name in the `name` field.
+* Have a verbose description. Do not simply re-phrase the `name` field. e.g.
+  instead of "Python linting for BITS", consider "Python static analysis checks.
+  Uses ruff for formatting and linting and pyright for type hinting."
+* Make use of the `categories` metadata field when possible.
+
+#### Add your files to CODEOWNERS
+
+While we want to keep this repo manageable, we also want to give teams enough
+leeway to maintain their own tools without constantly getting in their way. When
+adding your workflow template, add both files to
+[CODEOWNERS](./.github/CODEOWNERS) along with your team. This way, after the
+initial PR, teams can update and modify their own workflows without waiting on
+review from BITS. More details are available in the CODEOWNERS file.

mkdocs.yml

@@ -0,0 +1,8 @@
+---
+site_name: "Broad Institute default files"
+
+nav:
+  - Home: "README.md"
+
+plugins:
+  - "techdocs-core"