Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
173 lines (133 loc) · 11.8 KB

CONTRIBUTING.md

File metadata and controls

173 lines (133 loc) · 11.8 KB
Raw

Contributing documentation and training material

Choose the content type first

  • Software page: one concise landing page per maintained tool.
  • Tutorial: a focused, reproducible task with a bounded outcome.
  • Workflow: an end-to-end analysis that may span several tools or packages.
  • Guide: decision support, orientation, or a recommended route through the ecosystem.
  • Concept: a concise explanation of an analytical idea that supports multiple tutorials.
  • Workshop: event-focused material; may later link to maintained tutorials and workflows.
  • Reference: remains with the package unless it is genuinely cross-package.

Required software metadata

Every file in software/ describes one tool. The Software page (software.qmd) groups and filters tools from this metadata, so each field has one job:

---
title: "AlloMate"
description: "Genetic mate allocation and breeding optimization that balances gain and inbreeding."
domain: Pedigree & Mating
status: released
form: R Shiny app
tasks: [Mate allocation, Kinship]
tags: [OCS, Optimum contribution selection, Breeding optimization]
ecosystem: breedverse
access: "Visit the landing page for more information:"
links:
  online: https://breeding-insight.github.io/AlloMate/
  docs:
  website:
  cran:
  source: https://github.com/Breeding-Insight/AlloMate
  releases: https://github.com/Breeding-Insight/AlloMate/releases
image: ../assets/software/logos/software-allomate.png
image-alt: "AlloMate hexagonal logo."
---
Field Values Used for
domain Exactly one of: Data Management, Genomic Analysis, Pedigree & Mating, Markers & Haplotypes, Phenomics, Utilities Page sections and the Domain filter. Every domain is listed in the sidebar, in this order, even with no tools yet; a section appears on the page once a tool uses that domain. Utilities tools are not shown on the home page hub.
status released or in-development In-development tools are listed in their own "In development" section below all released tools, with an amber "In development" badge, and their tool page opens with an "In development" notice (assets/lua-extensions/tool-status.lua). Also drives the sidebar's Status filter. Change to released when the tool ships.
version, version-date, version-url Generated by scripts/fetch-releases.py The latest published GitHub release of the repository in links.source, shown after the tool name on its card and as a badge linking to the release on its tool page. The weekly "Update news from releases" workflow keeps them current; do not edit by hand. Tools with no published release show no version.
version-source: manual Optional For a tool with no GitHub release: set version by hand and the sync leaves the page alone. Remove it once the repository publishes a release.
release-repo Optional repository name, e.g. bi-web Use when a tool's releases are published in a different Breeding-Insight repository than links.source (DeltaBreed's are in bi-web). The version sync reads releases from this repository instead.
form One of: Web app, R Shiny app, R package, Python package, Mobile app The Type filter and the badge on each card.
tasks Up to 3 from: GWAS, Genomic selection, Population structure, Ploidy, CNV, Microhaplotypes, MADC processing, Mate allocation, Kinship, Pedigree, Parentage, Ancestry, Data management, Phenotypic analysis, Image processing Shown first among the card's tags and listed under Task in the sidebar. Use [] when none fit.
tags Free text Shown on the card after the tasks and listed under Other tags in the sidebar (collapsed by default, most-used first). Use for acronyms, file formats, platforms, and narrow terms (OCS, DArTag, VCF, Aneuploidy). Avoid repeating the domain or type.
ecosystem breedverse or omitted The Breedverse badge.
links.online The app's GitHub Pages landing page The "Runs online" badge and filter. Also add a "Use online" button to the tool page's "Start here" section, tagged for analytics: {.btn-bi-primary data-analytics-event="use_online" data-analytics-tool="<Tool>"}. Link the landing page, never the Cloud Run service URL.
access Short note, e.g. "Visit the landing page for more information:" Shown directly above the "Use online" button on the tool page: add [{{< meta access >}}]{.access-note} on the line before the button row. For apps behind ORCID sign-in, start the button text with <img class="orcid-icon" src="../assets/branding/orcid-icon.svg" alt="">.
links.docs, website, cran, source, releases URLs, any may be omitted Not shown on cards (each tool page has its own buttons); kept as structured data for later use.
image-wide true for wordmark logos Wider logo slot on cards.
image-shape square for logos that are not hexagons; app-icon for a logo that is already a rounded-square app icon (DeltaBreed) On the home page hub, the logo gets a square tile instead of a place in its domain's honeycomb (app-icon logos show without the tile's white frame). Hex logos (the default) tile together, so draw them as full-height pointy-top hexagons on a transparent background.
identifiers.doi, identifiers.rrid Optional, nested under identifiers: (a top-level doi would be printed by Quarto's title block). The bare DOI (10.1371/journal.pone.0324104) and the RRID number (SCR_026678) Shown above the intro text on the tool page (added by assets/tool-identifiers.lua) as identifier chips linking to doi.org and the SciCrunch resolver, and searchable on the Software page. Add them for every tool that has them.

The lists of allowed domain, form, and tasks values live at the top of assets/ejs-templates/software-listing.ejs.md. Rendering fails with a message naming the page if a value is not on those lists or a page lists more than 3 tasks. Add a new task only when it applies to at least two tools or is a task users would look for by name; otherwise use tags. Do not use categories on software pages.

Each tool page shows the same badges and tags as its card (type, "Breedverse", "Runs online", then tasks and tags) by placing {{< tool-tags >}} after the intro paragraph in the software-header block; each tag links to the Software page filtered by that tag. Do not hand-write badges on tool pages. The shortcode lives in assets/lua-extensions/tool-tags.lua and is registered for all tool pages in software/_metadata.yml.

For a tool that can be installed and also runs online, split "Start here" into numbered options (see software/allomate.qmd): ### Run locally {.start-option data-step="1"} with the install code, then ### Run online {.start-option data-step="2"} with the access sentence, the access-note, and the "Use online" button on its own. Put the Source code / Releases buttons below both options in a ::: {.start-links} block. On any page with a "Use online" button, keep that button on its own and put the other buttons in a ::: {.start-links} block after it, which adds a divider.

Required learning metadata

Every file in learn/ should use the same metadata dimensions:

---
title: "From MADC output to analysis-ready VCF"
description: "Use BIGr to filter targeted sequencing data and create a standards-compliant VCF."
categories:
  - Genotype Data
  - Data Quality
  - Ploidy & Dosage
image: ../assets/software/logos/example.svg
order: 20
learning-type: Workflow
software:
  - BIGr
level: Intermediate
keywords:
  - DArTag
  - MADC
  - VCF
  - dosage
---

categories: broad user-facing topics

Use these as the primary discovery system. Prefer the controlled vocabulary below:

  • Getting Started
  • Genotype Data
  • Data Quality
  • Ploidy & Dosage
  • Population Analysis
  • Trait Mapping
  • Genomic Prediction

Add a new broad category only when multiple durable pages justify it. Do not put package names, difficulty levels, or one-off keywords in categories.

software: tools used by the material

Examples:

  • BIGr
  • BIGapp
  • Qploidy2
  • Familia
  • AlloMate
  • BIGpopA

A cross-package workflow may list several tools.

level: expected learner experience

Use exactly one:

  • Beginner
  • Intermediate
  • Advanced

learning-type: instructional form

Use exactly one:

  • Tutorial
  • Workflow
  • Guide
  • Concept

keywords: precise search terms

Use this for specific technologies, formats, methods, organisms, or analyses such as MADC, VCF, DArTag, GWAS, PCA, or alfalfa.

Writing expectations

  • State the biological or analytical goal before showing code.
  • Name required inputs and assumptions.
  • Provide a reproducible setup.
  • Explain consequential analytical decisions rather than only listing commands.
  • Use checkpoints after major transformations.
  • Show expected outputs where interpretation matters.
  • Document common failure modes.
  • Link to the next logical workflow.
  • Do not duplicate canonical API reference text.

Discovery behavior on software.qmd

The Software page uses a custom listing template (assets/ejs-templates/software-listing.ejs.md) that groups tools by domain and writes their metadata into data attributes. assets/html-scripts/software-filter.html builds the sidebar from the tools present: search, then collapsible Domain, Status (collapsed by default), Task, and Type sections, a "Runs online" switch, and a collapsed Other tags section, each with counts (long lists show the first 8 with "Show all"). Checking several values in one section widens the results; checking values in different sections narrows them. Clicking a tag on a card selects it in the sidebar. Clicking anywhere else on a card opens the tool page, which holds the install, source, and "Use online" links. Filter state is kept in the URL (?domain=, ?type=, ?tag=, ?online=1, ?search=, repeatable) so filtered views can be shared; the Cards/List choice and which sidebar sections are open are remembered per browser. On narrow screens the sidebar folds into a Filters button above the results.

Each card's markup lives in assets/ejs-templates/software-card.ejs.md, shared with the Featured software section on the home page. To change which tools are featured, edit the listing: contents: list in index.qmd; the cards there come from the same tool metadata, and their tags link to the Software page filtered by that tag.

Discovery behavior on learn.qmd

The Learn page uses the Software page's layout (body class software-hub-page) and a custom listing template (assets/ejs-templates/learn-listing.ejs.md). Each card shows learning-type, level, and software as badges (software prefixed with Uses) and broad categories as topic tags. assets/html-scripts/learn-filter.html builds the sidebar from the materials present: search, then Format, Topic, Software, and Level checkboxes with counts. Checking several values in one section widens the results; checking values in different sections narrows them. Clicking a topic tag on a card, or a goal chip under the title, selects that topic. Filter state is kept in the URL (?type=, ?topic=, ?software=, ?level=, ?learn-q=, repeatable), so links such as learn.html?topic=Genomic%20Prediction#all-learning-materials open a filtered view.

Concept page pattern

Concept pages should be concise enough to read before a workflow but substantial enough to prevent common analytical misunderstandings. Prefer this order:

  1. One-sentence definition.
  2. A small concrete example.
  3. The distinction users most often miss.
  4. Practical consequences for breeding/genomics analysis.
  5. A short takeaway.
  6. Links to the next tutorial or workflow.
  7. A small set of primary or authoritative further-reading sources.

Do not turn a Concept page into package API reference. Package-specific function arguments remain canonical in the package documentation.