From 57f2d0e305d6d4bc4d19d0af47830d1a6ee008c2 Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Tue, 24 Mar 2026 17:37:10 -0600 Subject: [PATCH 01/33] Add GitHub Actions for Sphinx documentation build and update dependency check workflow --- .github/workflows/docs.yml | 39 ++++++++++++++++++++++++++++++++++++++ .github/workflows/test.yml | 18 +++++++++++------- 2 files changed, 50 insertions(+), 7 deletions(-) create mode 100644 .github/workflows/docs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..6fd9323 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,39 @@ +name: Docs Build + +# Builds the Sphinx docs on every PR to verify nothing is broken before merge. +# This is separate from ReadTheDocs, which publishes the live site on push to main. +# -W turns warnings into errors (catches broken references, bad toctree entries, etc.) +# -n enables nitpicky mode (flags missing references) +# --keep-going collects all errors instead of stopping at the first one +on: + pull_request: + types: [opened, synchronize, reopened, ready_for_review] + +jobs: + sphinx: + name: Build Sphinx docs + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install Poetry + run: python -m pip install poetry + + - name: Install dependencies + run: poetry install + + - name: Build docs (warnings = errors) + # -W treat warnings as errors + # -n nitpicky mode — flag all missing references + # --keep-going collect every error before failing (don't stop at first) + run: | + poetry run sphinx-build -W --keep-going -n \ + docs/source docs/source/build + + diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index c1729b6..9fbee47 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -1,13 +1,17 @@ name: Dependency Check +# Verifies that the Poetry dependency lock-file resolves cleanly across the +# supported Python range. Doc building is handled by the separate docs.yml job. on: pull_request: - types: [opened, synchronize, edited] + types: [opened, synchronize, edited, reopened] jobs: build: + name: Install deps (Python ${{ matrix.python-version }}, ${{ matrix.os }}) runs-on: ${{ matrix.os }} strategy: + fail-fast: false matrix: os: [ubuntu-latest, macos-latest] python-version: ['3.10', '3.11'] @@ -16,12 +20,12 @@ jobs: shell: bash steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: python-version: ${{ matrix.python-version }} - - uses: Gr1N/setup-poetry@v8 - - name: Install dependencies and app - run: | - poetry install + - name: Install Poetry + run: python -m pip install poetry + - name: Install dependencies + run: poetry install From 6acedaf7e0ddbfedf6f1253a397df639b1812c53 Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Tue, 24 Mar 2026 17:51:11 -0600 Subject: [PATCH 02/33] Update documentation formatting and ensure all pages listed in toctree --- docs/source/conf.py | 3 +++ .../data_management/digital_object_identifiers.md | 8 ++++---- docs/source/data_management/index.rst | 1 + .../python/packaging_and_distribution.md | 4 ++-- .../workflows/docker/beginner_guide_to_docker.md | 2 +- docs/source/workflows/docker/index.rst | 1 - .../generative_ai_tools_at_lasp.md | 2 +- docs/source/workflows/generative_ai_tools/index.rst | 3 ++- docs/source/workflows/index.rst | 1 + docs/source/workflows/jenkins_job_builder/index.rst | 4 ---- docs/source/workflows/open_source/pull_requests.md | 11 +++++------ 11 files changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index c8a8be9..55b9445 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -21,6 +21,9 @@ 'sphinx.ext.viewcode', ] +# Generate heading anchors for H1–H3 so that #slug links in .md files resolve +myst_heading_anchors = 3 + templates_path = ['_templates'] exclude_patterns = [] source_suffix = { diff --git a/docs/source/data_management/digital_object_identifiers.md b/docs/source/data_management/digital_object_identifiers.md index 4f50203..ae614eb 100644 --- a/docs/source/data_management/digital_object_identifiers.md +++ b/docs/source/data_management/digital_object_identifiers.md @@ -51,7 +51,7 @@ To enable accessibility, a DOI needs to reside in a registry where it can be resolved. The registry collects and provides high level information, assigns DOIs, and links to references. -#### [DataCite](https://datacite.org/) +### [DataCite](https://datacite.org/) DataCite is a not-for-profit, global initiative to "help the research community locate, identify, and cite research data with confidence," through DOI minting @@ -71,7 +71,7 @@ membership, LASP can mint and register DOIs for datasets housed in our repositories, enabling data to be persistently identified, accessed, and cited. -#### [Crossref](https://www.crossref.org/) +### [Crossref](https://www.crossref.org/) Crossref is another registry that is often mentioned in Earth and space science contexts. It's a not-for-profit association of ~2000 voting member publishers @@ -79,7 +79,7 @@ who represent 4300 societies and publishers. It exists to facilitate the links between distributed content hosted at other sites, and uses DOIs to do so. -#### [Zenodo](https://zenodo.org/) +### [Zenodo](https://zenodo.org/) Zenodo is a free repository developed by CERN and operated by OpenAIRE. It is a general-purpose repository that allows researchers to deposit datasets, @@ -89,7 +89,7 @@ content, making it citable and discoverable. See [citing software](../workflows/open_source/citing_software.md) for more on using Zenodo to cite software. -#### [ORCiDs](https://orcid.org/) +### [ORCiDs](https://orcid.org/) ORCiDs are like DOIs but provide persistent digital object identifiers for people. diff --git a/docs/source/data_management/index.rst b/docs/source/data_management/index.rst index af80a50..c024ed1 100644 --- a/docs/source/data_management/index.rst +++ b/docs/source/data_management/index.rst @@ -5,6 +5,7 @@ Data Management .. toctree:: :maxdepth: 1 + data_management file_formats/index metadata.md fair_principles.md diff --git a/docs/source/programming_languages/python/packaging_and_distribution.md b/docs/source/programming_languages/python/packaging_and_distribution.md index 6b6626c..026c9bf 100644 --- a/docs/source/programming_languages/python/packaging_and_distribution.md +++ b/docs/source/programming_languages/python/packaging_and_distribution.md @@ -285,8 +285,8 @@ package and optionally also written to a version.py file so it remains accessibl The options for Python packaging and distribution that we often see used at LASP are: -- [PyPI](#packaging-for-pypi--pip-install-) -- [Conda](#packaging-for-conda--conda-install-) +- [PyPI](#packaging-for-pypi-pip-install) +- [Conda](#packaging-for-conda-conda-install) ## Packaging for PyPI (`pip install`) diff --git a/docs/source/workflows/docker/beginner_guide_to_docker.md b/docs/source/workflows/docker/beginner_guide_to_docker.md index e26de31..b368f2f 100644 --- a/docs/source/workflows/docker/beginner_guide_to_docker.md +++ b/docs/source/workflows/docker/beginner_guide_to_docker.md @@ -92,7 +92,7 @@ rebuild, and you can find a full list of flags [here](https://docs.docker.com/re Now that we have built the image, we can see all the Docker images that are built on our system by running the `docker images` command: -```plaintext +```text $ docker images REPOSITORY TAG IMAGE ID CREATED SIZE docker_tutorial latest 71736be7c555 5 minutes ago 91.9MB diff --git a/docs/source/workflows/docker/index.rst b/docs/source/workflows/docker/index.rst index 95356b1..dbc629c 100644 --- a/docs/source/workflows/docker/index.rst +++ b/docs/source/workflows/docker/index.rst @@ -10,6 +10,5 @@ Docker containerizing_idl_with_docker docker_compose_examples export_display_with_docker - jenkins_job_builder multi_stage_builds running_docker_with_m1 \ No newline at end of file diff --git a/docs/source/workflows/generative_ai_tools/generative_ai_tools_at_lasp.md b/docs/source/workflows/generative_ai_tools/generative_ai_tools_at_lasp.md index c797ccd..8c72b6c 100644 --- a/docs/source/workflows/generative_ai_tools/generative_ai_tools_at_lasp.md +++ b/docs/source/workflows/generative_ai_tools/generative_ai_tools_at_lasp.md @@ -52,7 +52,7 @@ or assistance from their supervisors, contract officials, compliance officers, a risks and ensure adherence to all relevant guidelines, regulations, laws, and institutional policies. While LASP does not have an official organizational element defined to administer and support the use of Generative AI tools, questions can be posed to the #chatgpt Slack channel for general guidance. Feedback or questions can be provided -to your [ITGC](/pages/viewpage.action?pageId=139193455) representatives. +to your ITGC representatives. ## Terminology diff --git a/docs/source/workflows/generative_ai_tools/index.rst b/docs/source/workflows/generative_ai_tools/index.rst index 8ffb425..b5b9e12 100644 --- a/docs/source/workflows/generative_ai_tools/index.rst +++ b/docs/source/workflows/generative_ai_tools/index.rst @@ -4,4 +4,5 @@ Generative AI Tools .. toctree:: :maxdepth: 1 - generative_ai_tools_at_lasp \ No newline at end of file + generative_ai_tools_at_lasp + activating_github_copilot diff --git a/docs/source/workflows/index.rst b/docs/source/workflows/index.rst index 7b7f3e6..584cd96 100644 --- a/docs/source/workflows/index.rst +++ b/docs/source/workflows/index.rst @@ -5,6 +5,7 @@ Workflows :maxdepth: 1 docker/index + jenkins_job_builder/index open_source/index generative_ai_tools/index diff --git a/docs/source/workflows/jenkins_job_builder/index.rst b/docs/source/workflows/jenkins_job_builder/index.rst index 4c20208..39fa302 100644 --- a/docs/source/workflows/jenkins_job_builder/index.rst +++ b/docs/source/workflows/jenkins_job_builder/index.rst @@ -5,7 +5,3 @@ Jenkins Job Builder :maxdepth: 1 containerize_jjb - containerize_jenkins_with_jjb - jjb_initialization_file - jjb_job_definition_files - jjb_scripts_and_templates \ No newline at end of file diff --git a/docs/source/workflows/open_source/pull_requests.md b/docs/source/workflows/open_source/pull_requests.md index 3e824f8..52dfd7c 100644 --- a/docs/source/workflows/open_source/pull_requests.md +++ b/docs/source/workflows/open_source/pull_requests.md @@ -1,9 +1,9 @@ -## Pull Request and Review Standards +# Pull Request and Review Standards Before any code is merged into the code base, it will need to be put up for pull request (PR) and reviewed. The pull request should be created following the checklist for pull requests. -### Checklist for Pull Requests +## Checklist for Pull Requests * Read through your own diff and look for weirdness. e.g. mistakes or accidental changes * Update the changelog, if one exists. @@ -26,7 +26,7 @@ Ask the following questions: * Does the code include new unit tests? * Are any new dependencies correctly added to the ``pyproject.toml`` file? -### Before opening a pull request +## Before opening a pull request Before you create the pull request, you should go through the checklist for pull requests to ensure the proposed changes meet the repository standards. @@ -39,7 +39,7 @@ initial design. If you put up a draft PR, indicate whether or not you are lookin Finally, if you are addressing an existing issue, make sure that issue is [linked](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) in your PR. If there is not an existing issue, then you should either create an issue or address WHY you are opening the PR specifically. -### During review +## During review As a reviewer, please follow these rules of thumb: @@ -61,7 +61,7 @@ As a team: 1. Don't take comments personally - treat everyone as a fellow team member working to produce excellent code, not as adversaries to defeat before you can merge 1. Be honest - if you disagree with someones comment, start a discussion on why that is the case -### Before merging +## Before merging Before merging, a pull request needs one approving review. While the review is open, anyone can make comments or request changes on the PR. @@ -74,4 +74,3 @@ Although only one approval is required, you must follow these rules: 1. You should go through the pull request checklist. 1. You should ensure ALL checks on the PR pass (tests are passing) 1. If you have a lot of commits, clean up the commits by running a [rebase](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) and combining commits. - From cfa2a2c165c2b9dccd2720f2a23659f3aaab2d60 Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Tue, 24 Mar 2026 18:15:33 -0600 Subject: [PATCH 03/33] Add markdownlint and yamllint configurations for consistent linting --- .markdownlint.yaml | 57 +++++++++++++++++++++++++++++++++++ .mdl_style.rb | 2 +- .mdlrc | 2 +- .pre-commit-config.yaml | 67 +++++++++++++++++++++++++++++++++++------ .readthedocs.yaml | 2 +- .yamllint.yaml | 25 +++++++++++++++ 6 files changed, 143 insertions(+), 12 deletions(-) create mode 100644 .markdownlint.yaml create mode 100644 .yamllint.yaml diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000..d97b7e5 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,57 @@ +# Markdownlint configuration for markdownlint-cli (Node.js) +# Rule reference: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md +# +# This mirrors the exclusions in .mdl_style.rb (used by the Ruby mdl gem) +# so both tools agree. The .mdlrc / .mdl_style.rb files can be retired once +# the team is fully on markdownlint-cli. + +default: true + +# -- Line length -------------------------------------------------------------- +# 120 chars max; code blocks and tables are exempt (same as .mdl_style.rb) +MD013: + line_length: 120 + code_blocks: false + tables: false + headings: false + +# -- Disabled rules (match .mdl_style.rb exclusions) ------------------------- +MD014: false # Dollar signs before commands without showing output — allowed +MD029: false # Ordered list item prefix — allow repeating "1." style +MD033: false # Inline HTML — allowed +MD034: false # Bare URLs — allowed +MD036: false # Emphasis used instead of a heading — allowed + +# -- Additional sensible rules ------------------------------------------------ +# Enforce consistent heading style (ATX = # style, not underline style) +MD003: + style: atx + +# Enforce consistent unordered list marker (* vs - vs +) +MD004: + style: consistent + +# No multiple blank lines +MD012: + maximum: 1 + +# No hard tabs +MD010: + spaces_per_tab: 4 + +# Fenced code blocks should have a language specified +MD040: true + +# No trailing punctuation in headings +MD026: + punctuation: ".,;:!" + +# -- Disabled rules (repo convention) ----------------------------------------- +# The guideline template consistently uses 2-space sub-bullets under numbered +# lists (e.g., 1. **Step** \n - detail). Enforcing MD007 would require +# rewriting every How-to-Apply section across the whole site. +MD007: false + +# Tight lists (no blank lines between items) are idiomatic in this repo's +# guideline pages. MD032 would require blank lines around every list block. +MD032: false diff --git a/.mdl_style.rb b/.mdl_style.rb index 3d3a7cf..a8bf164 100644 --- a/.mdl_style.rb +++ b/.mdl_style.rb @@ -4,4 +4,4 @@ exclude_rule 'MD033' # Inline HTML exclude_rule 'MD034' # Bare URL used exclude_rule 'MD036' # Emphasis used instead of a header -rule 'MD013', :line_length => 120, :ignore_code_blocks => true, :tables => false \ No newline at end of file +rule 'MD013', :line_length => 120, :ignore_code_blocks => true, :tables => false diff --git a/.mdlrc b/.mdlrc index f7152f1..74a339a 100644 --- a/.mdlrc +++ b/.mdlrc @@ -1 +1 @@ -style "#{File.dirname(__FILE__)}/.mdl_style.rb" \ No newline at end of file +style "#{File.dirname(__FILE__)}/.mdl_style.rb" diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index b49a93f..b6c3bf5 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,21 +1,70 @@ ci: autofix_prs: false autoupdate_schedule: 'quarterly' + repos: + # --------------------------------------------------------------------------- + # General file hygiene + # --------------------------------------------------------------------------- - repo: https://github.com/pre-commit/pre-commit-hooks rev: v5.0.0 hooks: - - id: check-added-large-files - args: ['--maxkb=1000'] - - id: detect-aws-credentials - args: [--allow-missing-credentials] - - id: detect-private-key - - id: mixed-line-ending - - id: trailing-whitespace - - id: no-commit-to-branch - args: [--branch, main] + - id: check-added-large-files # block files > 1 MB + args: ['--maxkb=1000'] + - id: check-case-conflict # catch Mac/Windows case insensitivity bugs + - id: check-merge-conflict # catch leftover <<<< ==== >>>> markers + - id: check-yaml # validate all YAML files (workflows, config) + - id: detect-aws-credentials + args: [--allow-missing-credentials] + - id: detect-private-key + - id: end-of-file-fixer # ensure every file ends with a newline + - id: mixed-line-ending + - id: no-commit-to-branch + args: [--branch, main] + - id: trailing-whitespace + # --markdown-linebreak-ext preserves intentional two-space line breaks in .md + args: [--markdown-linebreak-ext=md] + + # --------------------------------------------------------------------------- + # Markdown linting + # Config: .markdownlint.yaml (mirrors the existing .mdl_style.rb exclusions) + # --------------------------------------------------------------------------- + - repo: https://github.com/igorshubovych/markdownlint-cli + rev: v0.43.0 + hooks: + - id: markdownlint + args: [--config, .markdownlint.yaml] + + # --------------------------------------------------------------------------- + # reStructuredText validation (toctree, directives, broken references) + # --------------------------------------------------------------------------- + - repo: https://github.com/rstcheck/rstcheck + rev: v6.2.4 + hooks: + - id: rstcheck + additional_dependencies: ['rstcheck-core', 'sphinx'] + args: [--report-level=warning] + + # --------------------------------------------------------------------------- + # YAML linting — catches style issues in workflow files and config + # Config: .yamllint.yaml + # --------------------------------------------------------------------------- + - repo: https://github.com/adrienverge/yamllint + rev: v1.35.1 + hooks: + - id: yamllint + args: [--config-file, .yamllint.yaml] + + # --------------------------------------------------------------------------- + # Spell checking (.md, .rst, .yml) + # --------------------------------------------------------------------------- - repo: https://github.com/codespell-project/codespell rev: v2.4.1 hooks: - id: codespell files: ^.*\.(md|rst|yml)$ + args: + # nd/ND = Creative Commons "No Derivatives" + # SORCE = Solar Radiation and Climate Experiment (NASA mission) + # sav = IDL save file extension + - --ignore-words-list=nd,ND,SORCE,sav diff --git a/.readthedocs.yaml b/.readthedocs.yaml index d5a54c7..4898346 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -19,4 +19,4 @@ build: - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install sphinx: - configuration: docs/source/conf.py \ No newline at end of file + configuration: docs/source/conf.py diff --git a/.yamllint.yaml b/.yamllint.yaml new file mode 100644 index 0000000..9c09b41 --- /dev/null +++ b/.yamllint.yaml @@ -0,0 +1,25 @@ +# yamllint configuration +# Docs: https://yamllint.readthedocs.io/en/stable/configuration.html +--- +extends: default + +rules: + # Match the project's 120-char line limit; URLs in comments are exempt + line-length: + max: 120 + allow-non-breakable-words: true + allow-non-breakable-inline-mappings: true + + # GitHub Actions uses `on:` as a top-level key; yamllint flags it as a + # truthy value by default, so we explicitly allow it + truthy: + allowed-values: ['true', 'false'] + check-keys: false # disables the 'on:' / 'yes:' key warning + + # Allow both block and flow sequences + braces: + min-spaces-inside: 0 + max-spaces-inside: 1 + + # Require documents to start with --- only in non-workflow YAML + document-start: disable From d1bf9fa0d256aff9f5b351e9f2870ce11c12b038 Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Tue, 24 Mar 2026 18:15:39 -0600 Subject: [PATCH 04/33] Update .gitignore to include docs/build directory --- .gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 09ba2e0..21ac933 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,3 @@ .idea/ docs/source/build -docs/build \ No newline at end of file +docs/build From 3862fcd871fbf5ee497e5a2fb20375e60e1ecb8f Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Tue, 24 Mar 2026 18:16:11 -0600 Subject: [PATCH 05/33] Refactor documentation for markdownlint --- CODE_OF_CONDUCT.md | 2 +- docs/README.md | 2 +- .../citing_and_publishing_datasets.md | 13 ++-- .../digital_object_identifiers.md | 8 ++- docs/source/how_to_write_docs.md | 71 ++++++++++++++----- .../python/best_practices.md | 2 +- .../python/packaging_and_distribution.md | 4 +- .../docker/advanced_guide_to_docker.md | 3 +- .../docker/developing_in_devcontainers.md | 2 - .../generative_ai_tools_at_lasp.md | 2 +- .../workflows/open_source/code_of_conduct.md | 66 ++++++++++++----- .../workflows/open_source/pull_requests.md | 63 ++++++++++------ 12 files changed, 164 insertions(+), 74 deletions(-) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 7e87d57..70aae31 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -100,4 +100,4 @@ For answers to common questions about this code of conduct, see the FAQ at [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 \ No newline at end of file +[translations]: https://www.contributor-covenant.org/translations diff --git a/docs/README.md b/docs/README.md index 44e654d..cfebb16 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,4 +6,4 @@ cd docs/source poetry run sphinx-build . build # View the documentation locally open build/index.html -``` \ No newline at end of file +``` diff --git a/docs/source/data_management/citing_and_publishing_datasets.md b/docs/source/data_management/citing_and_publishing_datasets.md index 4ad9af1..fb27c89 100644 --- a/docs/source/data_management/citing_and_publishing_datasets.md +++ b/docs/source/data_management/citing_and_publishing_datasets.md @@ -5,18 +5,21 @@ openly accessible, properly identified with DOIs, and cited according to communi aligns with publisher and funder policies and promotes scientific reproducibility. ## Dataset Publishing and Citation Workflow + The process of publishing and citing datasets involves several key steps: -1. **Understand Publisher Requirements** - [DOIs](digital_object_identifiers.md) and [ORCIDs](https://orcid.org/) may be required by publishers to maintain compliance with submission guidelines +1. **Understand Publisher Requirements** - [DOIs](digital_object_identifiers.md) and + [ORCIDs](https://orcid.org/) may be required by publishers to maintain compliance with + submission guidelines 2. **Make Data Open and Accessible** - Store datasets in publicly accessible, machine-readable formats -3. **Create a DOI and Landing Page** - Register a persistent identifier that resolves to a landing page with comprehensive dataset information. +3. **Create a DOI and Landing Page** - Register a persistent identifier that resolves to a + landing page with comprehensive dataset information. 4. **Maintain Metadata** - Keep DOI metadata accurate and up to date 5. **Cite Datasets Properly** - Follow established data citation principles in publications. Reference the [Force 11 Joint Declaration of Data Citation Principles](https://www.force11.org/datacitationprinciples) and follow practices described in the [ESIP Dataset Citation Guidelines](https://doi.org/10.6084/m9.figshare.8441816). - -## Publishing Options: +## Publishing Options 1. **LASP Data Management Group** This group can assist with minting a DOI for LASP hosted datasets and provide guidance on navigating CU resources @@ -41,6 +44,7 @@ The process of publishing and citing datasets involves several key steps: process for LASP-affiliated data products. ## Quick Start Guide + As of 2018, CU Libraries is a member of DataCite. Through this membership, LASP can mint and register a limited number of DOIs for datasets housed in our repositories, enabling data to be persistently identified, accessed, and cited. For LASP-affiliated datasets, researchers can work with the LASP Data Management team @@ -82,7 +86,6 @@ to create DOIs and get advice on CU resources available to support publishing da ![DataCite_Repository_Guidelines](../_static/repository_obligations_table.png) - ## Useful Links - [CU Scholar](https://scholar.colorado.edu/about) diff --git a/docs/source/data_management/digital_object_identifiers.md b/docs/source/data_management/digital_object_identifiers.md index ae614eb..793e646 100644 --- a/docs/source/data_management/digital_object_identifiers.md +++ b/docs/source/data_management/digital_object_identifiers.md @@ -52,6 +52,7 @@ where it can be resolved. The registry collects and provides high level information, assigns DOIs, and links to references. ### [DataCite](https://datacite.org/) + DataCite is a not-for-profit, global initiative to "help the research community locate, identify, and cite research data with confidence," through DOI minting @@ -72,6 +73,7 @@ housed in our repositories, enabling data to be persistently identified, accessed, and cited. ### [Crossref](https://www.crossref.org/) + Crossref is another registry that is often mentioned in Earth and space science contexts. It's a not-for-profit association of ~2000 voting member publishers @@ -80,6 +82,7 @@ facilitate the links between distributed content hosted at other sites, and uses DOIs to do so. ### [Zenodo](https://zenodo.org/) + Zenodo is a free repository developed by CERN and operated by OpenAIRE. It is a general-purpose repository that allows researchers to deposit datasets, @@ -90,6 +93,7 @@ See [citing software](../workflows/open_source/citing_software.md) for more on using Zenodo to cite software. ### [ORCiDs](https://orcid.org/) + ORCiDs are like DOIs but provide persistent digital object identifiers for people. @@ -126,6 +130,7 @@ Note that DOI names are not case-sensitive, while URLs are case-sensitive: https://support.datacite.org/docs/datacite-doi-display-guidelines. ## Navigating Options at LASP + There are internal and external options available for creating DOIs for various types of products including datasets, software, and presentations. If you're not sure where to start, reach out to the LASP Data Management team for guidance by submitting @@ -133,7 +138,6 @@ a Jira issue with type "DOI" in the [Data Management Jira project](https://jira. ![Diagram of DOI creation and management options at LASP](../_static/doi_options.png) - ## Useful Links - [DataCite: DOI Basics](https://support.datacite.org/docs/doi-basics) @@ -146,4 +150,4 @@ a Jira issue with type "DOI" in the [Data Management Jira project](https://jira. - **IDF** = International DOI Foundation - **ORCID** = Open Researcher and Contributor ID -Credit: Content taken from a Confluence guide written by Anne Wilson and Shawn Polson. \ No newline at end of file +Credit: Content taken from a Confluence guide written by Anne Wilson and Shawn Polson. diff --git a/docs/source/how_to_write_docs.md b/docs/source/how_to_write_docs.md index 2b1acee..f857ed9 100644 --- a/docs/source/how_to_write_docs.md +++ b/docs/source/how_to_write_docs.md @@ -4,40 +4,75 @@ The main goals of our technical documentation are: -- **Be clear**: Documentation should be easy to read and understand, with acronyms defined and referenced information linked out -- **Be findable**: Documentation pages should be in a logical location, with clear focus and scope, and an accurate title -- **Be in existence**: Documentation should be created, rather than not. This also means that it should be easy to write documentation, without excessive requirements, rules, or expectations -- **Be accurate**: This goal is aided by the first two goals, but it also requires a team commitment to remove or correct inaccurate documentation. It is better to have no documentation than it is to have inaccurate documentation, so delete anything you see that is wrong. - -This documentation should be focused on internal team members, without worrying about external partners, but it should also be easy to read for even new team members who have very little context or background knowledge. +- **Be clear**: Documentation should be easy to read and understand, with acronyms defined and + referenced information linked out +- **Be findable**: Documentation pages should be in a logical location, with clear focus and scope, + and an accurate title +- **Be in existence**: Documentation should be created, rather than not. This also means that it + should be easy to write documentation, without excessive requirements, rules, or expectations +- **Be accurate**: This goal is aided by the first two goals, but it also requires a team commitment + to remove or correct inaccurate documentation. It is better to have no documentation than it is + to have inaccurate documentation, so delete anything you see that is wrong. + +This documentation should be focused on internal team members, without worrying about external +partners, but it should also be easy to read for even new team members who have very little context +or background knowledge. ## Rules and Best Practices -- Documentation pages should be short and refined in scope. This helps with goals 1 + 2, by making each piece of information in a page directly related to the title, and to make linking information in other pages easier. -- Be cautious about adding additional broad categories or top-level pages. This helps with goal 2, by making sure it is easy to start a search at a high level and dig down. Try to keep organization flat. -- In existence is better than perfect. A documentation page doesn't need to be complete. It doesn't need to cover every piece of information. Having an incomplete page is better than no page. This ties into rule 3. If you aren't sure about something, write it down anyway and note that. -- If you're writing out a long explanation or context, make a docs page and link it instead. Instead of having broader context, technical designs, or frequently asked questions scattered across the ephemeral world of tickets, slack messages, and emails, create it once and link it from then on. -- It should be easy to create documentation. This ties into rule 3 and 1. It should be easy to create documentation, without excessive requirements or rules either from the team or from yourself. -- Correct or remove outdated information as you find it. The other side of making documentation easy to write is making it easy to remove. Every team member should feel empowered to move, edit, or delete any and all pages. Again, missing information is preferable to inaccurate documentation. All documentation is ephemeral. -- Reduce the amount of duplicate information. Writing something down in multiple places makes it more difficult to find, and makes it harder to correct. Ways to reduce this happening are 1) keeping pages short 2) linking instead of making subsections and 3) combining pages if you do find duplicates. +- Documentation pages should be short and refined in scope. This helps with goals 1 + 2, by making + each piece of information in a page directly related to the title, and to make linking information + in other pages easier. +- Be cautious about adding additional broad categories or top-level pages. This helps with goal 2, + by making sure it is easy to start a search at a high level and dig down. Try to keep organization + flat. +- In existence is better than perfect. A documentation page doesn't need to be complete. It doesn't + need to cover every piece of information. Having an incomplete page is better than no page. This + ties into rule 3. If you aren't sure about something, write it down anyway and note that. +- If you're writing out a long explanation or context, make a docs page and link it instead. Instead + of having broader context, technical designs, or frequently asked questions scattered across the + ephemeral world of tickets, slack messages, and emails, create it once and link it from then on. +- It should be easy to create documentation. This ties into rule 3 and 1. It should be easy to + create documentation, without excessive requirements or rules either from the team or from + yourself. +- Correct or remove outdated information as you find it. The other side of making documentation easy + to write is making it easy to remove. Every team member should feel empowered to move, edit, or + delete any and all pages. Again, missing information is preferable to inaccurate documentation. + All documentation is ephemeral. +- Reduce the amount of duplicate information. Writing something down in multiple places makes it more + difficult to find, and makes it harder to correct. Ways to reduce this happening are 1) keeping + pages short 2) linking instead of making subsections and 3) combining pages if you do find + duplicates. - Avoid "misc" or catch-all pages or places. These make finding and organizing information very difficult. ## Types of Pages -This is a brief description of some of the pages that you may find or create within this sphere. Not every page neatly fits into these categories and they are not prescriptive. +This is a brief description of some of the pages that you may find or create within this sphere. +Not every page neatly fits into these categories and they are not prescriptive. ### Overview Pages -These are basic descriptions of the world as it is. This could describe relationships with external partners, background on the mission, documentation on the existing design of infrastructure. Resist the urge to make this too detailed - it shouldn't replace documentation of the code, but should instead act as an easy place to point people if they ask questions like - "what is the camera radiometry? What is it doing? When should it be used?" +These are basic descriptions of the world as it is. This could describe relationships with external +partners, background on the mission, documentation on the existing design of infrastructure. Resist +the urge to make this too detailed - it shouldn't replace documentation of the code, but should +instead act as an easy place to point people if they ask questions like - "what is the camera +radiometry? What is it doing? When should it be used?" ### Flow diagrams -Similarly to overview pages, these are images or flow diagrams which supplement overview pages. These can be a powerful visualization for difficult to convey information. +Similarly to overview pages, these are images or flow diagrams which supplement overview pages. +These can be a powerful visualization for difficult to convey information. ### How-to pages -These are descriptions of how to accomplish a specific task. This might include "how to open a pull request" or "how to fix this specific bug" +These are descriptions of how to accomplish a specific task. This might include "how to open a +pull request" or "how to fix this specific bug" ### Design Documents and Whitepapers -These are documents which describe some proposed future work or a future design. They can be as detailed as including a complete description of future work and the roadmap to get there, or as simple as a comparison between two technologies or a proposed solution for a problem. The key factor is that they are for future work, and therefore, should try to avoid descriptions of existing designs. Rather, they should link out to existing overview pages, to reduce duplicate work and ensure that any new information is not lost once the design doc is complete and no longer used. +These are documents which describe some proposed future work or a future design. They can be as +detailed as including a complete description of future work and the roadmap to get there, or as +simple as a comparison between two technologies or a proposed solution for a problem. The key factor +is that they are for future work, and therefore, should try to avoid descriptions of existing +designs. Rather, they should link out to existing overview pages, to reduce duplicate work and +ensure that any new information is not lost once the design doc is complete and no longer used. diff --git a/docs/source/programming_languages/python/best_practices.md b/docs/source/programming_languages/python/best_practices.md index 74b8512..7bbbc27 100644 --- a/docs/source/programming_languages/python/best_practices.md +++ b/docs/source/programming_languages/python/best_practices.md @@ -210,7 +210,7 @@ Usage:: Notes: - Use action words ("Return") rather than descriptions ("Returns"). -- Document __init__ methods in the docstring for the class. +- Document `__init__` methods in the docstring for the class. ```python class Person(object): diff --git a/docs/source/programming_languages/python/packaging_and_distribution.md b/docs/source/programming_languages/python/packaging_and_distribution.md index 026c9bf..3a8936c 100644 --- a/docs/source/programming_languages/python/packaging_and_distribution.md +++ b/docs/source/programming_languages/python/packaging_and_distribution.md @@ -52,8 +52,8 @@ Some resources that describe the path by which we arrived where we are: ### Working definitions -Package: A directory containing python modules and an __init__.py file. -Subpackage: A package directory containing an __init__.py file, which is itself contained inside an enclosing package. +Package: A directory containing python modules and an `__init__.py` file. +Subpackage: A package directory containing an `__init__.py` file, which is itself contained inside an enclosing package. Module: A python file that can be imported, possibly as part of a package or subpackage. ### Package Structure diff --git a/docs/source/workflows/docker/advanced_guide_to_docker.md b/docs/source/workflows/docker/advanced_guide_to_docker.md index ca3c9a9..fbe508b 100644 --- a/docs/source/workflows/docker/advanced_guide_to_docker.md +++ b/docs/source/workflows/docker/advanced_guide_to_docker.md @@ -89,11 +89,10 @@ you've ever wondered how a Docker container isolated to a Linux VM can bind-moun makes that work seamlessly. In fact, the VM defaults to mounting your home directory to exactly the same path, so while it _seems_ like your bind-mount commands reflect your host filesystem, they really reflect the path inside the VM. -``` +```text Mac Filesystem -> Linux VM -> Docker Container ``` Don't accept this default! Choose exactly what data your Docker containers should be able to access by limiting what your Linux VM is allowed to mount. Remember that the bind-mount path you give to your containers is really the path to the data _inside the Linux VM_. - diff --git a/docs/source/workflows/docker/developing_in_devcontainers.md b/docs/source/workflows/docker/developing_in_devcontainers.md index a5a1962..87da614 100644 --- a/docs/source/workflows/docker/developing_in_devcontainers.md +++ b/docs/source/workflows/docker/developing_in_devcontainers.md @@ -23,7 +23,6 @@ Cons: - Bind-mounts are slow because file system changes are propagated through layers of OS translation from container, to VM, to host. - ## Volume-Mounting Code Alternatively, you can store your repo code (or really anything you want to work on) inside a Docker volume that lives @@ -43,7 +42,6 @@ Cons: git remote but any .gitignored files will be gone. - Less flexible. You don't get free access to your host filesystem. You only get your repo. - ## SSH and GPG Keys In pretty much any dev environment, you need access to SSH keys and GPG keys for authenticating with repositories diff --git a/docs/source/workflows/generative_ai_tools/generative_ai_tools_at_lasp.md b/docs/source/workflows/generative_ai_tools/generative_ai_tools_at_lasp.md index 8c72b6c..302c21a 100644 --- a/docs/source/workflows/generative_ai_tools/generative_ai_tools_at_lasp.md +++ b/docs/source/workflows/generative_ai_tools/generative_ai_tools_at_lasp.md @@ -77,4 +77,4 @@ to your ITGC representatives. * [NASA FAQ on use of LLMs like ChatGPT](https://science.nasa.gov/researchers/sara/faqs/#faq-32) * [Using Generative AI for Scientific Research (a guide from the University of Michigan)](https://midas.umich.edu/generative-ai-user-guide/) -*Credit: Content taken from a Confluence guide created by Chris Pankratz, and last updated by Alex Ware on Jan 09, 2025* \ No newline at end of file +*Credit: Content taken from a Confluence guide created by Chris Pankratz, and last updated by Alex Ware on Jan 09, 2025* diff --git a/docs/source/workflows/open_source/code_of_conduct.md b/docs/source/workflows/open_source/code_of_conduct.md index 908d41e..49cb9c5 100644 --- a/docs/source/workflows/open_source/code_of_conduct.md +++ b/docs/source/workflows/open_source/code_of_conduct.md @@ -1,24 +1,52 @@ # LASP Open Source Code of Conduct -We expect all "lasp" organization projects to adopt a code of conduct that ensures a productive, respectful environment for all open source contributors and participants. We are committed to providing a strong and enforced code of conduct and expect everyone in our community to follow these guidelines when interacting with others in all forums. Our goal is to keep ours a positive, inclusive, successful, and growing community. The community of participants in open source Astronomy projects is made up of members from around the globe with a diverse set of skills, personalities, and experiences. It is through these differences that our community experiences success and continued growth. - +We expect all "lasp" organization projects to adopt a code of conduct that ensures a productive, +respectful environment for all open source contributors and participants. We are committed to +providing a strong and enforced code of conduct and expect everyone in our community to follow +these guidelines when interacting with others in all forums. Our goal is to keep ours a positive, +inclusive, successful, and growing community. The community of participants in open source Astronomy +projects is made up of members from around the globe with a diverse set of skills, personalities, +and experiences. It is through these differences that our community experiences success and continued +growth. As members of the community, -- We pledge to treat all people with respect and provide a harassment- and bullying-free environment, regardless of sex, sexual orientation and/or gender identity, disability, physical appearance, body size, race, nationality, ethnicity, and religion. In particular, sexual language and imagery, sexist, racist, or otherwise exclusionary jokes are not appropriate. - -- We pledge to respect the work of others by recognizing acknowledgment/citation requests of original authors. As authors, we pledge to be explicit about how we want our own work to be cited or acknowledged. - -- We pledge to welcome those interested in joining the community, and realize that including people with a variety of opinions and backgrounds will only serve to enrich our community. In particular, discussions relating to pros/cons of various technologies, programming languages, and so on are welcome, but these should be done with respect, taking proactive measure to ensure that all participants are heard and feel confident that they can freely express their opinions. - -- We pledge to welcome questions and answer them respectfully, paying particular attention to those new to the community. We pledge to provide respectful criticisms and feedback in forums, especially in discussion threads resulting from code contributions. - -- We pledge to be conscientious of the perceptions of the wider community and to respond to criticism respectfully. We will strive to model behaviors that encourage productive debate and disagreement, both within our community and where we are criticized. We will treat those outside our community with the same respect as people within our community. - -- We pledge to help the entire community follow the code of conduct, and to not remain silent when we see violations of the code of conduct. We will take action when members of our community violate this code such as such as contacting LASP organization admins or talking privately with the person. - -This code of conduct applies to all community situations online and offline, including mailing lists, forums, social media, conferences, meetings, associated social events, and one-to-one interactions. - -Parts of this code of conduct have been adapted from the [Astropy](http://www.astropy.org/code_of_conduct.html) and [Numfocus](https://www.numfocus.org/about/code-of-conduct/) codes of conduct. - -This code of conduct is based on the [SpaceTelescope code of conduct](https://github.com/spacetelescope/style-guides/blob/75d52647344f85527d9b60b6bf38bde46d30e2b2/templates/CODE_OF_CONDUCT.md). \ No newline at end of file +- We pledge to treat all people with respect and provide a harassment- and bullying-free environment, + regardless of sex, sexual orientation and/or gender identity, disability, physical appearance, body + size, race, nationality, ethnicity, and religion. In particular, sexual language and imagery, + sexist, racist, or otherwise exclusionary jokes are not appropriate. + +- We pledge to respect the work of others by recognizing acknowledgment/citation requests of + original authors. As authors, we pledge to be explicit about how we want our own work to be cited + or acknowledged. + +- We pledge to welcome those interested in joining the community, and realize that including people + with a variety of opinions and backgrounds will only serve to enrich our community. In particular, + discussions relating to pros/cons of various technologies, programming languages, and so on are + welcome, but these should be done with respect, taking proactive measure to ensure that all + participants are heard and feel confident that they can freely express their opinions. + +- We pledge to welcome questions and answer them respectfully, paying particular attention to those + new to the community. We pledge to provide respectful criticisms and feedback in forums, especially + in discussion threads resulting from code contributions. + +- We pledge to be conscientious of the perceptions of the wider community and to respond to + criticism respectfully. We will strive to model behaviors that encourage productive debate and + disagreement, both within our community and where we are criticized. We will treat those outside + our community with the same respect as people within our community. + +- We pledge to help the entire community follow the code of conduct, and to not remain silent when + we see violations of the code of conduct. We will take action when members of our community + violate this code such as such as contacting LASP organization admins or talking privately with + the person. + +This code of conduct applies to all community situations online and offline, including mailing +lists, forums, social media, conferences, meetings, associated social events, and one-to-one +interactions. + +Parts of this code of conduct have been adapted from the +[Astropy](http://www.astropy.org/code_of_conduct.html) and +[Numfocus](https://www.numfocus.org/about/code-of-conduct/) codes of conduct. + +This code of conduct is based on the +[SpaceTelescope code of conduct](https://github.com/spacetelescope/style-guides/blob/75d52647344f85527d9b60b6bf38bde46d30e2b2/templates/CODE_OF_CONDUCT.md). diff --git a/docs/source/workflows/open_source/pull_requests.md b/docs/source/workflows/open_source/pull_requests.md index 52dfd7c..9b08cce 100644 --- a/docs/source/workflows/open_source/pull_requests.md +++ b/docs/source/workflows/open_source/pull_requests.md @@ -1,7 +1,7 @@ # Pull Request and Review Standards -Before any code is merged into the code base, it will need to be put up for pull request (PR) and reviewed. The pull request should be created following -the checklist for pull requests. +Before any code is merged into the code base, it will need to be put up for pull request (PR) and +reviewed. The pull request should be created following the checklist for pull requests. ## Checklist for Pull Requests @@ -28,16 +28,24 @@ Ask the following questions: ## Before opening a pull request -Before you create the pull request, you should go through the checklist for pull requests to ensure the proposed changes meet the repository standards. +Before you create the pull request, you should go through the checklist for pull requests to ensure +the proposed changes meet the repository standards. -The PR should be as small as possible. However, the code included in the PR should be complete. All code merged into the main branch should meet the repository standards and work as expected. +The PR should be as small as possible. However, the code included in the PR should be complete. +All code merged into the main branch should meet the repository standards and work as expected. -If you want to work on the pull request or are not yet finished with the code, please indicate this by marking the pull request as a -[draft or WIP](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests) PR. -Anyone looking at the PR will be able to quickly see it is not final. Marking your PR as draft means you are asking someone for an initial review, or if you want to get comments on your -initial design. If you put up a draft PR, indicate whether or not you are looking for initial reviews in the summary. +If you want to work on the pull request or are not yet finished with the code, please indicate this +by marking the pull request as a +[draft or WIP](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests) +PR. Anyone looking at the PR will be able to quickly see it is not final. Marking your PR as draft +means you are asking someone for an initial review, or if you want to get comments on your initial +design. If you put up a draft PR, indicate whether or not you are looking for initial reviews in +the summary. -Finally, if you are addressing an existing issue, make sure that issue is [linked](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) in your PR. If there is not an existing issue, then you should either create an issue or address WHY you are opening the PR specifically. +Finally, if you are addressing an existing issue, make sure that issue is +[linked](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) +in your PR. If there is not an existing issue, then you should either create an issue or address +WHY you are opening the PR specifically. ## During review @@ -45,32 +53,47 @@ As a reviewer, please follow these rules of thumb: 1. Comments should be clear in addressing why you want to see the change 1. Comments should be polite, but straightforward and candid -1. If you leave a review, continue to follow up on replies to your questions or comments and review the changes you requested -1. It is nice, but not required, to provide examples for suggestions (particularly for things like name changes) -1. If you require a change to be addressed, add a "request changes" comment. If you make one of these comments, it means you are blocking the code review from merging until that change is addressed. -1. If you make a "request changes" comment, you must create a follow up review where you change that to an approving review (or make another "request changes" review). Please do this in a timely matter so you do not block the PR for longer than necessary. +1. If you leave a review, continue to follow up on replies to your questions or comments and review + the changes you requested +1. It is nice, but not required, to provide examples for suggestions (particularly for things like + name changes) +1. If you require a change to be addressed, add a "request changes" comment. If you make one of + these comments, it means you are blocking the code review from merging until that change is + addressed. +1. If you make a "request changes" comment, you must create a follow up review where you change that + to an approving review (or make another "request changes" review). Please do this in a timely + matter so you do not block the PR for longer than necessary. As an author: -1. If you would like to request a specific review from someone, make sure they are marked as a reviewer or called out in a comment on the review (by typing `@`) +1. If you would like to request a specific review from someone, make sure they are marked as a + reviewer or called out in a comment on the review (by typing `@`) 1. Please respond to PR comments in a timely manner and according to the LASP Code of Conduct As a team: 1. All parties need to be respectful during code reviews and follow the LASP Code of Conduct -1. Don't take comments personally - treat everyone as a fellow team member working to produce excellent code, not as adversaries to defeat before you can merge +1. Don't take comments personally - treat everyone as a fellow team member working to produce + excellent code, not as adversaries to defeat before you can merge 1. Be honest - if you disagree with someones comment, start a discussion on why that is the case ## Before merging -Before merging, a pull request needs one approving review. While the review is open, anyone can make comments or request changes on the PR. +Before merging, a pull request needs one approving review. While the review is open, anyone can +make comments or request changes on the PR. Although only one approval is required, you must follow these rules: -1. If you know there is someone with a particular expertise or vested interest in your changes, **do not merge or close the pull request until they get a chance to review.** -1. Do not merge until you have addressed all the comments on your review, even if you have an approval from someone. +1. If you know there is someone with a particular expertise or vested interest in your changes, + **do not merge or close the pull request until they get a chance to review.** +1. Do not merge until you have addressed all the comments on your review, even if you have an + approval from someone. 1. Make sure you have left the review open for a sufficient amount of time to allow people to review. -1. If someone asked for changes beyond a nitpick, do not merge until you have an approval or thumbs up from them. This does not mean you need to change your code if you don't agree with them, but you should explain why you will not be making the changes and make sure they are ok with merging anyway. +1. If someone asked for changes beyond a nitpick, do not merge until you have an approval or thumbs + up from them. This does not mean you need to change your code if you don't agree with them, but + you should explain why you will not be making the changes and make sure they are ok with merging + anyway. 1. You should go through the pull request checklist. 1. You should ensure ALL checks on the PR pass (tests are passing) -1. If you have a lot of commits, clean up the commits by running a [rebase](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) and combining commits. +1. If you have a lot of commits, clean up the commits by running a + [rebase](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) and combining commits. From 80cb4caabbbe632f7b4f8b9c1e4ac0e6ca6b6fb8 Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Tue, 24 Mar 2026 18:16:19 -0600 Subject: [PATCH 06/33] Update codespell ignore-words-list with explanations for clarity --- pyproject.toml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 64a3187..6725ba5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -37,4 +37,7 @@ homepage = "https://github.com/lasp/" repository = "https://github.com/lasp/developer-guide" [tool.codespell] -ignore-words-list = "nd, SORCE, sav" +# nd/ND = "No Derivatives" (Creative Commons license term) +# SORCE = Solar Radiation and Climate Experiment (NASA mission) +# sav = IDL save file extension (.sav) +ignore-words-list = "nd,ND,SORCE,sav" From c15ec85a001eb0e7aebbfe299bb34cbaa0a04a24 Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Tue, 24 Mar 2026 18:16:25 -0600 Subject: [PATCH 07/33] Fix missing newline at end of file in conf.py --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 55b9445..6548dcd 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -42,4 +42,4 @@ # Add the custom CSS file to the list of stylesheets def setup(app): - app.add_css_file('css/custom.css') \ No newline at end of file + app.add_css_file('css/custom.css') From 7334f8c64c8a0b4097d77f9b7c7ead784b4e6cca Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Tue, 24 Mar 2026 18:16:30 -0600 Subject: [PATCH 08/33] Remove unnecessary blank lines in docs.yml --- .github/workflows/docs.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 6fd9323..3a1b6fa 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -35,5 +35,3 @@ jobs: run: | poetry run sphinx-build -W --keep-going -n \ docs/source docs/source/build - - From 6067579d9649635ffef908dfea9bd87d132daf5f Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Tue, 24 Mar 2026 18:16:39 -0600 Subject: [PATCH 09/33] Add missing newlines at the end of files in index.rst --- docs/source/data_management/file_formats/index.rst | 2 +- docs/source/data_management/index.rst | 2 +- docs/source/workflows/docker/index.rst | 2 +- docs/source/workflows/index.rst | 1 - docs/source/workflows/open_source/index.rst | 2 +- 5 files changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/source/data_management/file_formats/index.rst b/docs/source/data_management/file_formats/index.rst index bde309f..8b7eeb4 100644 --- a/docs/source/data_management/file_formats/index.rst +++ b/docs/source/data_management/file_formats/index.rst @@ -5,4 +5,4 @@ File Formats .. toctree:: :maxdepth: 1 - netcdf.md \ No newline at end of file + netcdf.md diff --git a/docs/source/data_management/index.rst b/docs/source/data_management/index.rst index c024ed1..85fe8b5 100644 --- a/docs/source/data_management/index.rst +++ b/docs/source/data_management/index.rst @@ -11,4 +11,4 @@ Data Management fair_principles.md data_stewardship.md citing_and_publishing_datasets.md - digital_object_identifiers.md \ No newline at end of file + digital_object_identifiers.md diff --git a/docs/source/workflows/docker/index.rst b/docs/source/workflows/docker/index.rst index dbc629c..f708a21 100644 --- a/docs/source/workflows/docker/index.rst +++ b/docs/source/workflows/docker/index.rst @@ -11,4 +11,4 @@ Docker docker_compose_examples export_display_with_docker multi_stage_builds - running_docker_with_m1 \ No newline at end of file + running_docker_with_m1 diff --git a/docs/source/workflows/index.rst b/docs/source/workflows/index.rst index 584cd96..418f488 100644 --- a/docs/source/workflows/index.rst +++ b/docs/source/workflows/index.rst @@ -8,4 +8,3 @@ Workflows jenkins_job_builder/index open_source/index generative_ai_tools/index - diff --git a/docs/source/workflows/open_source/index.rst b/docs/source/workflows/open_source/index.rst index 13b97e2..26044b1 100644 --- a/docs/source/workflows/open_source/index.rst +++ b/docs/source/workflows/open_source/index.rst @@ -8,4 +8,4 @@ Open Source citing_software.md lasp_github_org.md code_of_conduct.md - pull_requests.md \ No newline at end of file + pull_requests.md From 21fa40a04854add556d71c39ad2a58a249b4522e Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Tue, 24 Mar 2026 18:16:44 -0600 Subject: [PATCH 10/33] Add missing newline at end of LICENSE file --- LICENSE | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/LICENSE b/LICENSE index fd20d47..6644f74 100644 --- a/LICENSE +++ b/LICENSE @@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. \ No newline at end of file +SOFTWARE. From 312117f0187cc4025ffd242910738c6bf6c1cf2e Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Tue, 24 Mar 2026 18:18:25 -0600 Subject: [PATCH 11/33] Update codespell ignore-words-list with additional comments for clarity --- pyproject.toml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 6725ba5..b081f7c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -37,7 +37,5 @@ homepage = "https://github.com/lasp/" repository = "https://github.com/lasp/developer-guide" [tool.codespell] -# nd/ND = "No Derivatives" (Creative Commons license term) -# SORCE = Solar Radiation and Climate Experiment (NASA mission) -# sav = IDL save file extension (.sav) +# NOTE: These need to be added to .pre-commit-config.yaml to be ignored. ignore-words-list = "nd,ND,SORCE,sav" From 592e91532198dbf64d1435f0e6e444e4776ed0a6 Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Tue, 24 Mar 2026 18:24:58 -0600 Subject: [PATCH 12/33] Enable autofix for pre-commit.ci and update markdownlint and codespell configurations --- .pre-commit-config.yaml | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index b6c3bf5..2662318 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,6 +1,16 @@ ci: - autofix_prs: false + # pre-commit.ci (https://pre-commit.ci) — free for open-source repos. + # When enabled, it runs all hooks on every PR and commits any auto-fixes + # back to the PR branch automatically (no local setup required for contributors). + # Hooks that can auto-fix: end-of-file-fixer, trailing-whitespace, + # mixed-line-ending, markdownlint (--fix), codespell (--write-changes). + # Hooks that only detect (still require a human fix): check-yaml, + # check-merge-conflict, rstcheck, yamllint. + autofix_prs: true autoupdate_schedule: 'quarterly' + # rstcheck needs a full Sphinx/Poetry environment that pre-commit.ci + # doesn't have — skip it there and let docs.yml in GitHub Actions cover it. + skip: [rstcheck] repos: # --------------------------------------------------------------------------- @@ -33,7 +43,11 @@ repos: rev: v0.43.0 hooks: - id: markdownlint - args: [--config, .markdownlint.yaml] + # --fix auto-corrects issues that have a safe mechanical fix + # (blank lines around headings, trailing punctuation, etc.). + # Issues that require human judgement (line length, missing code + # fence language) are still reported as errors. + args: [--fix, --config, .markdownlint.yaml] # --------------------------------------------------------------------------- # reStructuredText validation (toctree, directives, broken references) @@ -64,6 +78,9 @@ repos: - id: codespell files: ^.*\.(md|rst|yml)$ args: + # --write-changes auto-corrects unambiguous spelling mistakes. + # Ambiguous corrections (multiple candidates) are still reported. + - --write-changes # nd/ND = Creative Commons "No Derivatives" # SORCE = Solar Radiation and Climate Experiment (NASA mission) # sav = IDL save file extension From 04c09952d7694879d4c7b2c1d6695c59c1f76a6d Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Tue, 24 Mar 2026 18:25:14 -0600 Subject: [PATCH 13/33] Remove missing section in index --- docs/source/workflows/generative_ai_tools/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/workflows/generative_ai_tools/index.rst b/docs/source/workflows/generative_ai_tools/index.rst index b5b9e12..d99e49b 100644 --- a/docs/source/workflows/generative_ai_tools/index.rst +++ b/docs/source/workflows/generative_ai_tools/index.rst @@ -5,4 +5,3 @@ Generative AI Tools :maxdepth: 1 generative_ai_tools_at_lasp - activating_github_copilot From b37955f953fa91f336c4b653e24b59b44e038694 Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Tue, 24 Mar 2026 18:29:22 -0600 Subject: [PATCH 14/33] Opt into Node.js 24 for all actions in the workflow --- .github/workflows/docs.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 3a1b6fa..52206b4 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -9,6 +9,12 @@ on: pull_request: types: [opened, synchronize, reopened, ready_for_review] +# Opt into Node.js 24 for all actions in this workflow. +# Remove once actions/checkout and actions/setup-python release +# versions that natively target Node.js 24. +env: + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true + jobs: sphinx: name: Build Sphinx docs From 3a2a823329ef873fa861f2376007ab4ac7643bcf Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Tue, 24 Mar 2026 18:29:27 -0600 Subject: [PATCH 15/33] Opt into Node.js 24 for all actions in the workflow --- .github/workflows/test.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 9fbee47..3a49d3f 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -6,6 +6,12 @@ on: pull_request: types: [opened, synchronize, edited, reopened] +# Opt into Node.js 24 for all actions in this workflow. +# Remove once actions/checkout and actions/setup-python release +# versions that natively target Node.js 24. +env: + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true + jobs: build: name: Install deps (Python ${{ matrix.python-version }}, ${{ matrix.os }}) From 1279e0c2f66396dbf5b691360c661286ab38c4f2 Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Tue, 24 Mar 2026 18:34:51 -0600 Subject: [PATCH 16/33] Add fail_on_warning to ReadTheDocs configuration and enhance Sphinx build output summary --- .github/workflows/docs.yml | 48 ++++++++++++++++++++++++++++---------- .readthedocs.yaml | 1 + 2 files changed, 37 insertions(+), 12 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 52206b4..bb408df 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,17 +1,16 @@ name: Docs Build -# Builds the Sphinx docs on every PR to verify nothing is broken before merge. -# This is separate from ReadTheDocs, which publishes the live site on push to main. -# -W turns warnings into errors (catches broken references, bad toctree entries, etc.) -# -n enables nitpicky mode (flags missing references) -# --keep-going collects all errors instead of stopping at the first one +# Fast CI error-gate: catches broken toctrees, bad references, and Sphinx +# warnings before merge. Runs in ~2 min. +# +# The live browsable preview is handled by ReadTheDocs, which posts its own +# status check ("docs/readthedocs.com") with a direct URL when a PR build +# completes. Enable it once in the RTD dashboard: +# Admin → Advanced Settings → "Build pull requests for this project" ✓ on: pull_request: types: [opened, synchronize, reopened, ready_for_review] -# Opt into Node.js 24 for all actions in this workflow. -# Remove once actions/checkout and actions/setup-python release -# versions that natively target Node.js 24. env: FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true @@ -35,9 +34,34 @@ jobs: run: poetry install - name: Build docs (warnings = errors) - # -W treat warnings as errors - # -n nitpicky mode — flag all missing references - # --keep-going collect every error before failing (don't stop at first) + id: build + shell: bash run: | + set -o pipefail poetry run sphinx-build -W --keep-going -n \ - docs/source docs/source/build + docs/source docs/source/build 2>&1 | tee /tmp/sphinx-output.txt + + - name: Write job summary + if: always() + shell: bash + run: | + { + echo "## 📚 Sphinx Docs Build" + echo "" + if [ "${{ steps.build.outcome }}" = "success" ]; then + echo "### ✅ Build passed — no warnings" + else + echo "### ❌ Build failed — see warnings below" + fi + echo "" + echo "> 🔗 **Live preview:** see the **ReadTheDocs** status check below for a" + echo "> clickable URL to browse the built docs directly." + echo "" + echo "
Full Sphinx output" + echo "" + echo '```' + cat /tmp/sphinx-output.txt + echo '```' + echo "" + echo "
" + } >> "$GITHUB_STEP_SUMMARY" diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 4898346..63a2e39 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -20,3 +20,4 @@ build: sphinx: configuration: docs/source/conf.py + fail_on_warning: true From 2825f21201ab427d1a5bd7e5c3a2ec5f53f0979d Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Tue, 24 Mar 2026 18:41:55 -0600 Subject: [PATCH 17/33] Remove empty jenkins_job_builder section from index --- docs/source/workflows/index.rst | 1 - .../workflows/jenkins_job_builder/containerize_jjb.md | 9 --------- docs/source/workflows/jenkins_job_builder/index.rst | 7 ------- 3 files changed, 17 deletions(-) delete mode 100644 docs/source/workflows/jenkins_job_builder/containerize_jjb.md delete mode 100644 docs/source/workflows/jenkins_job_builder/index.rst diff --git a/docs/source/workflows/index.rst b/docs/source/workflows/index.rst index 418f488..5746c9b 100644 --- a/docs/source/workflows/index.rst +++ b/docs/source/workflows/index.rst @@ -5,6 +5,5 @@ Workflows :maxdepth: 1 docker/index - jenkins_job_builder/index open_source/index generative_ai_tools/index diff --git a/docs/source/workflows/jenkins_job_builder/containerize_jjb.md b/docs/source/workflows/jenkins_job_builder/containerize_jjb.md deleted file mode 100644 index c9cae4b..0000000 --- a/docs/source/workflows/jenkins_job_builder/containerize_jjb.md +++ /dev/null @@ -1,9 +0,0 @@ -# Containerize Jenkins Job Builder - -## Purpose for this guideline - -## Useful Links - -## Acronyms - -*Credit: Content taken from a Confluence guide written by Steven Mueller* diff --git a/docs/source/workflows/jenkins_job_builder/index.rst b/docs/source/workflows/jenkins_job_builder/index.rst deleted file mode 100644 index 39fa302..0000000 --- a/docs/source/workflows/jenkins_job_builder/index.rst +++ /dev/null @@ -1,7 +0,0 @@ -Jenkins Job Builder -=================== - -.. toctree:: - :maxdepth: 1 - - containerize_jjb From a5d2acc7f243a1871ccd48e68ce33af3b336344f Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Wed, 25 Mar 2026 06:36:29 -0600 Subject: [PATCH 18/33] update comment Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .yamllint.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.yamllint.yaml b/.yamllint.yaml index 9c09b41..d2f5364 100644 --- a/.yamllint.yaml +++ b/.yamllint.yaml @@ -21,5 +21,5 @@ rules: min-spaces-inside: 0 max-spaces-inside: 1 - # Require documents to start with --- only in non-workflow YAML + # Do not require documents to start with --- (document-start rule disabled) document-start: disable From ed888afc1f55d9cad253a979462625113ce3c22f Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Wed, 25 Mar 2026 06:37:38 -0600 Subject: [PATCH 19/33] include yaml in lint Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .pre-commit-config.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 2662318..00adece 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -70,13 +70,13 @@ repos: args: [--config-file, .yamllint.yaml] # --------------------------------------------------------------------------- - # Spell checking (.md, .rst, .yml) + # Spell checking (.md, .rst, .yml, .yaml) # --------------------------------------------------------------------------- - repo: https://github.com/codespell-project/codespell rev: v2.4.1 hooks: - id: codespell - files: ^.*\.(md|rst|yml)$ + files: ^.*\.(md|rst|ya?ml)$ args: # --write-changes auto-corrects unambiguous spelling mistakes. # Ambiguous corrections (multiple candidates) are still reported. From 210d5c19d8951a40d9b01708960c3aedf825534d Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Wed, 25 Mar 2026 08:28:17 -0600 Subject: [PATCH 20/33] Update README.md to enhance contributing guidelines and clarify documentation structure --- README.md | 155 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 105 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 13edfc3..ef43a4d 100644 --- a/README.md +++ b/README.md @@ -1,60 +1,118 @@ # developer-guide -This repository contains the source code for the LASP developer guide. This README serves as a guide for those who wish -to contribute. For more information about purpose, motivation, scope, and contents of the developer guide, see the -developer guide homepage here: http://lasp-developer-guide.readthedocs.io/. +This repository contains the source code for the LASP developer guide. This README serves as a +guide for those who wish to contribute. For more information about purpose, motivation, scope, and +contents of the developer guide, see the developer guide homepage here: +. ## Contributing +### First-time setup + +After cloning the repo, run these two commands once: + +```bash +pip install poetry pre-commit +poetry install # installs Sphinx and all doc dependencies +pre-commit install # wires up the git commit hooks +``` + +`pre-commit install` is important — it runs a set of checks automatically every time you +`git commit`, so formatting problems are caught locally before they ever reach CI. + +### Making changes + +1. Create a branch: `git checkout -b my-branch` +2. Edit or add `.md` files under `docs/source/` +3. Preview the docs locally (see below) +4. Commit — pre-commit hooks run automatically and fix what they can +5. If hooks modify files, `git add .` and commit again +6. Push and open a pull request + +### Previewing docs locally + +```bash +poetry run sphinx-build -n docs/source docs/source/build +open docs/source/build/index.html +``` + +To match CI exactly (warnings treated as errors): + +```bash +poetry run sphinx-build -W --keep-going -n docs/source docs/source/build +``` + +### Pre-commit hooks + +The following checks run automatically on every `git commit`: + +| Hook | What it catches / fixes | +|---|---| +| `trailing-whitespace` | Trailing spaces (auto-fixed) | +| `end-of-file-fixer` | Missing trailing newline (auto-fixed) | +| `check-merge-conflict` | Leftover `<<<<`/`>>>>` conflict markers | +| `check-yaml` | Syntax errors in YAML files | +| `check-case-conflict` | Filenames that differ only by case | +| `markdownlint` | Heading hierarchy, line length, blank lines (auto-fixes where safe) | +| `rstcheck` | Broken toctree entries and RST directives | +| `yamllint` | Style issues in workflow and config YAML | +| `codespell` | Spelling mistakes in `.md`, `.rst`, `.yml` (auto-fixes unambiguous ones) | + +To run all hooks manually against every file: + +```bash +poetry run pre-commit run --all-files +``` + +Hooks that can auto-fix (trailing whitespace, missing newlines, some Markdown issues, spelling) +will modify files and exit non-zero. Just `git add .` and commit again — the fixes are already +applied. + +### What happens when you open a pull request + +Two automated checks run on every PR: + +1. **GitHub Actions — "Build Sphinx docs"** (~2 min): builds the docs with warnings-as-errors. + Click **Details** on the check to see the full Sphinx output in the job summary. + +2. **ReadTheDocs — "docs/readthedocs.com"** (~5–8 min): builds a live preview of exactly what + the docs will look like if merged. Click **Details** for a direct URL you can open in any + browser — no login or download required. + +Both checks must pass before a PR can be merged. + ### Markdown -This project uses the Markdown language as the source code for all documentation. -[This Markdown Guide](https://markdownguide.org) is a good resource for learning/troubleshooting Markdown syntax (google, -StackOverflow, and ChatGPT are also useful for this). Additionally, new contributors are encouraged to look through the -existing documents for examples on how to use Markdown and how to contribute with consistent formatting. +This project uses Markdown for all documentation content. +[This Markdown Guide](https://markdownguide.org) is a good resource. New contributors are also +encouraged to look through existing documents for formatting examples. + +Line length is capped at **120 characters** (enforced by `markdownlint`). Code blocks and tables +are exempt. ### Organization -Documents in this developer guide are mainly organized by topic, and is subject to change as more documents are added -and the project evolves. If it is not clear where to place a new document, feel free to open a GitHub issue so that the -larger group of developers can discuss it. +Documents are organized by topic under `docs/source/`. If it is not clear where to place a new +document, open a GitHub issue so the group can discuss it. -### Consistency in formatting, language, and tone +Use `guideline_template.md` as the starting point for any new guideline page, and register the +new file in the nearest `index.rst` toctree. -We aim to have a consistent tone and use of language throughout the documentation. Some things to keep in mind when -contributing: +### Consistency in formatting, language, and tone * Avoid sharing opinions about topics without supporting facts * Stick to third-person language and avoid using first-person * Avoid jargon, acronyms, or abbreviations unless they are defined * Keep sentences and paragraphs concise; break up long blocks of text -* Follow a consistent capitalization style for headings, code terms, proper nouns, etc. -* Format code snippets consistently (indentation, language tags for syntax highlighting). +* Format code snippets consistently (always specify a language tag on fenced code blocks) ### What is out of scope * Do not include any credentials, usernames, passwords, etc. +* Do not include links or references to LASP internal resources * Do not include any material that is considered Controlled Unclassified Information (CUI) * Do not include informal meeting notes -### Template - -Please refer to the -[guideline template](https://github.com/lasp/developer-guide/blob/main/guideline_template.md) markdown file as a -template for new guidelines. This template should be considered as guidance, and not a hard rule -- sections may be -removed, added, or edited based on the contributor's discretion and what makes sense for the topic. - -### How to view the documentation as it appears on ReadTheDocs - -It is often helpful to view what the final product will look like while developing. To do this, one can build the -docs locally and view them in a local browser: - -```bash -cd docs/ -make clean && make html -open build/html/index.html -``` - ### git Workflow If you would like to contribute changes to the content of this repository, do the following: @@ -63,31 +121,28 @@ If you would like to contribute changes to the content of this repository, do th 2. Make a local clone of your fork: ```bash -git clone https://github.com//developer-guide.git # For HTTPS -git clone git@github.com:/developer-guide.git # For SSH +git clone https://github.com//developer-guide.git # HTTPS +git clone git@github.com:/developer-guide.git # SSH cd developer-guide/ ``` -3. Set your personal fork to point to an ``origin`` and ``upstream`` remote: +3. Set your personal fork to point to an `origin` and `upstream` remote: ```bash -git remote set-url origin git@github.com:/developer-guide.git # For SSH -git remote add upstream git@github.com:lasp/developer-guide.git # For SSH - -git remote set-url origin https://github.com//developer-guide.git # For HTTPS -git remote add upstream https://github.com/lasp/developer-guide.git # For HTTPS +git remote set-url origin git@github.com:/developer-guide.git +git remote add upstream git@github.com:lasp/developer-guide.git ``` -4. Install the ``pre-commit`` hooks (i.e. ``pre-commit install``) (you may need to ``pip install pre-commit`` first) -5. Create a branch on that personal fork (i.e. ``git checkout -b ``) -6. Commit changes (i.e. ``git add ``, ``git commit -m ``) -7. Push that branch to your fork (i.e. ``git push origin ``) -8. On the ``lasp`` repository, create a new pull request -9. Assign a reviewer -10. Iterate with the reviewer over any needed changes until the reviewer approves of the pull request. This may require - additional commits to the pull request. Once all changes are approved, merge the pull request. +4. Run the first-time setup steps above (`poetry install`, `pre-commit install`) +5. Create a branch: `git checkout -b ` +6. Make changes, commit (`git add `, `git commit -m ""`) +7. Push: `git push origin ` +8. Open a pull request against `lasp/developer-guide` +9. The automated checks will run; address any failures before requesting review +10. Iterate with reviewers until approved, then merge ## Questions? -Any questions about this effort may be directed to the ``#ds-best-practices-documentation`` Slack channel. +Any questions about this effort may be directed to the `#ds-best-practices-documentation` Slack +channel. From 89266aeb91fe996d4ee6dd1939c934b04902c1a4 Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Wed, 25 Mar 2026 08:37:22 -0600 Subject: [PATCH 21/33] Refine Sphinx Docs Build output formatting for clarity --- .github/workflows/docs.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index bb408df..f495af2 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -46,15 +46,15 @@ jobs: shell: bash run: | { - echo "## 📚 Sphinx Docs Build" + echo "## Sphinx Docs Build" echo "" if [ "${{ steps.build.outcome }}" = "success" ]; then - echo "### ✅ Build passed — no warnings" + echo "### Build passed — no warnings" else - echo "### ❌ Build failed — see warnings below" + echo "### Build failed — see warnings below" fi echo "" - echo "> 🔗 **Live preview:** see the **ReadTheDocs** status check below for a" + echo "> **Live preview:** see the **ReadTheDocs** status check below for a" echo "> clickable URL to browse the built docs directly." echo "" echo "
Full Sphinx output" From 417f941d90e432bcf6c401d146df8b9fcdadf86b Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Wed, 25 Mar 2026 10:17:38 -0600 Subject: [PATCH 22/33] Add CODEOWNERS file and PR triage workflow for automatic review requests to admins --- .github/CODEOWNERS | 6 ++++++ .github/workflows/pr-triage.yml | 31 +++++++++++++++++++++++++++++++ 2 files changed, 37 insertions(+) create mode 100644 .github/CODEOWNERS create mode 100644 .github/workflows/pr-triage.yml diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..889265e --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,6 @@ +# CODEOWNERS — automatic review suggestions +# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners +# GitHub automatically suggests dev-guide-admins as reviewers for all PRs. + +# Request review from dev-guide-admins team for all files +* @lasp/dev-guide-admins diff --git a/.github/workflows/pr-triage.yml b/.github/workflows/pr-triage.yml new file mode 100644 index 0000000..70a98ae --- /dev/null +++ b/.github/workflows/pr-triage.yml @@ -0,0 +1,31 @@ +name: PR Triage + +# Automatically request review from dev-guide-admins when a PR is marked ready for review. +# This eliminates the need for contributors to manually find and assign reviewers. +on: + pull_request_target: + types: [ready_for_review] + +permissions: + pull-requests: write + +env: + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true + +jobs: + triage: + name: Request review from triage team + runs-on: ubuntu-latest + + steps: + # Request review from the dev-guide-admins team on every ready-for-review PR + - name: Request review from dev-guide-admins + uses: actions/github-script@v7 + with: + script: | + await github.rest.pulls.requestReviewers({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: context.payload.pull_request.number, + team_reviewers: ['dev-guide-admins'], + }); From 8d6ec0e51e3f39bead1f6b45846535cbf753d7ee Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Thu, 26 Mar 2026 09:00:07 -0700 Subject: [PATCH 23/33] Simplify post_install comment in .readthedocs.yaml for clarity --- .readthedocs.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 63a2e39..64ed8d7 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -14,8 +14,7 @@ build: # https://python-poetry.org/docs/#installing-manually - python -m pip install poetry post_install: - # Install dependencies with 'docs' dependency group - # https://python-poetry.org/docs/managing-dependencies/#dependency-groups + # Install dependencies with Poetry - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install sphinx: From 7c8946dac8ab57da2ce3a77b4b33c7755cf9152d Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Thu, 26 Mar 2026 09:00:12 -0700 Subject: [PATCH 24/33] Fix typo in code of conduct regarding reporting violations --- docs/source/workflows/open_source/code_of_conduct.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/workflows/open_source/code_of_conduct.md b/docs/source/workflows/open_source/code_of_conduct.md index 49cb9c5..3f96194 100644 --- a/docs/source/workflows/open_source/code_of_conduct.md +++ b/docs/source/workflows/open_source/code_of_conduct.md @@ -37,7 +37,7 @@ As members of the community, - We pledge to help the entire community follow the code of conduct, and to not remain silent when we see violations of the code of conduct. We will take action when members of our community - violate this code such as such as contacting LASP organization admins or talking privately with + violate this code such as contacting LASP organization admins or talking privately with the person. This code of conduct applies to all community situations online and offline, including mailing From fbff1cee05bb15ba1538d241820784fc6e11deab Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Thu, 26 Mar 2026 09:00:18 -0700 Subject: [PATCH 25/33] Add conditional check for Sphinx output in GitHub step summary --- .github/workflows/docs.yml | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index f495af2..6f1ac6e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -57,11 +57,13 @@ jobs: echo "> **Live preview:** see the **ReadTheDocs** status check below for a" echo "> clickable URL to browse the built docs directly." echo "" - echo "
Full Sphinx output" - echo "" - echo '```' - cat /tmp/sphinx-output.txt - echo '```' - echo "" - echo "
" + if [ -f /tmp/sphinx-output.txt ]; then + echo "
Full Sphinx output" + echo "" + echo '```' + cat /tmp/sphinx-output.txt + echo '```' + echo "" + echo "
" + fi } >> "$GITHUB_STEP_SUMMARY" From 9d48594d006fc13adb4a20d44bed3a88c98b9522 Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Thu, 26 Mar 2026 09:00:32 -0700 Subject: [PATCH 26/33] Fix typos in pull_requests.md for clarity and correctness --- docs/source/workflows/open_source/pull_requests.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/workflows/open_source/pull_requests.md b/docs/source/workflows/open_source/pull_requests.md index 9b08cce..8cbfdb7 100644 --- a/docs/source/workflows/open_source/pull_requests.md +++ b/docs/source/workflows/open_source/pull_requests.md @@ -62,7 +62,7 @@ As a reviewer, please follow these rules of thumb: addressed. 1. If you make a "request changes" comment, you must create a follow up review where you change that to an approving review (or make another "request changes" review). Please do this in a timely - matter so you do not block the PR for longer than necessary. + manner so you do not block the PR for longer than necessary. As an author: @@ -75,7 +75,7 @@ As a team: 1. All parties need to be respectful during code reviews and follow the LASP Code of Conduct 1. Don't take comments personally - treat everyone as a fellow team member working to produce excellent code, not as adversaries to defeat before you can merge -1. Be honest - if you disagree with someones comment, start a discussion on why that is the case +1. Be honest - if you disagree with someone's comment, start a discussion on why that is the case ## Before merging From 38cf8ee7e883b94cb5ce63e8193fcb8eeb70ba0b Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Fri, 27 Mar 2026 10:31:08 -0700 Subject: [PATCH 27/33] Update markdownlint configuration to use markdownlint-cli2 and adjust rules --- .markdownlint.yaml | 7 ++++++- .pre-commit-config.yaml | 13 ++++++------- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/.markdownlint.yaml b/.markdownlint.yaml index d97b7e5..9e0e874 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -1,4 +1,4 @@ -# Markdownlint configuration for markdownlint-cli (Node.js) +# Markdownlint configuration for markdownlint-cli2 (Node.js) # Rule reference: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md # # This mirrors the exclusions in .mdl_style.rb (used by the Ruby mdl gem) @@ -55,3 +55,8 @@ MD007: false # Tight lists (no blank lines between items) are idiomatic in this repo's # guideline pages. MD032 would require blank lines around every list block. MD032: false + +# Table column alignment style is overly strict for contributors and produces +# false positives on wide-cell tables — disable until a consistent table style +# is established across the whole site. +MD060: false diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 00adece..7dbd634 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -38,15 +38,14 @@ repos: # --------------------------------------------------------------------------- # Markdown linting # Config: .markdownlint.yaml (mirrors the existing .mdl_style.rb exclusions) + # markdownlint-cli2 is the official CLI maintained by the markdownlint author (DavidAnson). # --------------------------------------------------------------------------- - - repo: https://github.com/igorshubovych/markdownlint-cli - rev: v0.43.0 + - repo: https://github.com/DavidAnson/markdownlint-cli2 + rev: v0.19.1 hooks: - - id: markdownlint - # --fix auto-corrects issues that have a safe mechanical fix - # (blank lines around headings, trailing punctuation, etc.). - # Issues that require human judgement (line length, missing code - # fence language) are still reported as errors. + - id: markdownlint-cli2 + # --fix auto-corrects issues with a safe mechanical fix. + # Issues requiring human judgement are still reported as errors. args: [--fix, --config, .markdownlint.yaml] # --------------------------------------------------------------------------- From 6d02ed803701a5ddc08f74ab8d1df7c0d49981c1 Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Fri, 27 Mar 2026 10:31:20 -0700 Subject: [PATCH 28/33] Improve clarity in Docker documentation by updating links and phrasing --- docs/source/workflows/docker/beginner_guide_to_docker.md | 2 +- docs/source/workflows/docker/multi_stage_builds.md | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/source/workflows/docker/beginner_guide_to_docker.md b/docs/source/workflows/docker/beginner_guide_to_docker.md index b368f2f..6bc2af9 100644 --- a/docs/source/workflows/docker/beginner_guide_to_docker.md +++ b/docs/source/workflows/docker/beginner_guide_to_docker.md @@ -87,7 +87,7 @@ The flag `–platform linux/amd64` is optional unless you are [running an M1 chi flag indicates the name of the Dockerfile -- in this case, it is also optional, since `Dockerfile` is the default value. The `-t` flag is a way to track the docker images and containers on our system by adding a name and a tag. `latest` is the tag used to indicate the latest version of a Docker image. Additional useful flags include `--no-cache` for a clean -rebuild, and you can find a full list of flags [here](https://docs.docker.com/reference/cli/docker/buildx/build/). +rebuild, and you can find a full list of flags in the [Docker build reference](https://docs.docker.com/reference/cli/docker/buildx/build/). Now that we have built the image, we can see all the Docker images that are built on our system by running the `docker images` command: diff --git a/docs/source/workflows/docker/multi_stage_builds.md b/docs/source/workflows/docker/multi_stage_builds.md index 92f6a12..e6f0c0c 100644 --- a/docs/source/workflows/docker/multi_stage_builds.md +++ b/docs/source/workflows/docker/multi_stage_builds.md @@ -117,8 +117,9 @@ version: "3.9" ENV_VAR: "test var" ``` -If you wanted to tag this image, you can find more info on doing that -[here](https://docs.docker.com/reference/compose-file/build/#consistency-with-image). +If you wanted to tag this image, see the +[Docker Compose build reference](https://docs.docker.com/reference/compose-file/build/#consistency-with-image) +for more info. With this docker compose file, you can build and run the Dockerfile with the following command: From 749c1d0d3c9b0eada2b009c7366e0db6c56b0df4 Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Fri, 27 Mar 2026 10:31:28 -0700 Subject: [PATCH 29/33] Enhance PR triage workflow by expanding review request triggers and adding fallback notifications --- .github/workflows/pr-triage.yml | 45 +++++++++++++++++++++++++-------- 1 file changed, 35 insertions(+), 10 deletions(-) diff --git a/.github/workflows/pr-triage.yml b/.github/workflows/pr-triage.yml index 70a98ae..caa9d3f 100644 --- a/.github/workflows/pr-triage.yml +++ b/.github/workflows/pr-triage.yml @@ -1,13 +1,16 @@ name: PR Triage -# Automatically request review from dev-guide-admins when a PR is marked ready for review. -# This eliminates the need for contributors to manually find and assign reviewers. +# Automatically request review from dev-guide-admins when a PR is ready for review. +# Covers two cases: +# - PR opened directly as ready for review (opened, reopened) +# - Draft PR converted to ready for review (ready_for_review) on: pull_request_target: - types: [ready_for_review] + types: [opened, reopened, ready_for_review] permissions: pull-requests: write + issues: write env: FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true @@ -15,17 +18,39 @@ env: jobs: triage: name: Request review from triage team + # Skip draft PRs — only run when the PR is actually ready for review + if: github.event.pull_request.draft == false runs-on: ubuntu-latest steps: - # Request review from the dev-guide-admins team on every ready-for-review PR - - name: Request review from dev-guide-admins + # Request review from the dev-guide-admins team. + # Also posts a comment mentioning the team as a reliable fallback notification, + # since requestReviewers can silently fail for teams in some org configurations. + - name: Request review and notify dev-guide-admins uses: actions/github-script@v7 with: script: | - await github.rest.pulls.requestReviewers({ - owner: context.repo.owner, - repo: context.repo.repo, - pull_number: context.payload.pull_request.number, - team_reviewers: ['dev-guide-admins'], + const pr = context.payload.pull_request.number; + const { owner, repo } = context.repo; + + // Attempt to assign the team as a formal reviewer + try { + await github.rest.pulls.requestReviewers({ + owner, + repo, + pull_number: pr, + team_reviewers: ['dev-guide-admins'], + }); + console.log('Successfully requested review from dev-guide-admins'); + } catch (err) { + // Log the error but don't fail — the comment below still notifies the team + console.error('requestReviewers failed:', err.message); + } + + // Post a comment mentioning the team so they are always notified + await github.rest.issues.createComment({ + owner, + repo, + issue_number: pr, + body: '@lasp/dev-guide-admins — this PR is ready for review.', }); From 57760c770247c0251d6a5ea42e9dfd6c7179ca23 Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Mon, 30 Mar 2026 09:28:26 -0600 Subject: [PATCH 30/33] orchid typo Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/source/data_management/digital_object_identifiers.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/data_management/digital_object_identifiers.md b/docs/source/data_management/digital_object_identifiers.md index 793e646..9be64a7 100644 --- a/docs/source/data_management/digital_object_identifiers.md +++ b/docs/source/data_management/digital_object_identifiers.md @@ -92,10 +92,10 @@ content, making it citable and discoverable. See [citing software](../workflows/open_source/citing_software.md) for more on using Zenodo to cite software. -### [ORCiDs](https://orcid.org/) +### [ORCID iDs](https://orcid.org/) -ORCiDs are like DOIs but provide -persistent digital object identifiers for people. +ORCID iDs are like DOIs but provide +persistent digital identifiers for researchers. ## DOI Format From 3267db61417f7f67caccafda87f045be7e86213b Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Mon, 30 Mar 2026 09:44:32 -0600 Subject: [PATCH 31/33] stop line length linting since it doesn't have auto fix --- .markdownlint.yaml | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 9e0e874..d8f3135 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -8,12 +8,10 @@ default: true # -- Line length -------------------------------------------------------------- -# 120 chars max; code blocks and tables are exempt (same as .mdl_style.rb) -MD013: - line_length: 120 - code_blocks: false - tables: false - headings: false +# Disabled: MD013 cannot be auto-fixed by markdownlint --fix (it would require +# editorial judgment about where to wrap prose). Enforcing it creates friction +# for contributors and has no effect on the rendered Sphinx/HTML output. +MD013: false # -- Disabled rules (match .mdl_style.rb exclusions) ------------------------- MD014: false # Dollar signs before commands without showing output — allowed From 9a993d92290d1f2e97bb31ae182d460482fe0088 Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Mon, 30 Mar 2026 09:48:29 -0600 Subject: [PATCH 32/33] allow "here" links --- .markdownlint.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.markdownlint.yaml b/.markdownlint.yaml index d8f3135..fc949b2 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -19,6 +19,7 @@ MD029: false # Ordered list item prefix — allow repeating "1." style MD033: false # Inline HTML — allowed MD034: false # Bare URLs — allowed MD036: false # Emphasis used instead of a heading — allowed +MD059: false # Descriptive link text — "here" links can't be auto-fixed; cosmetic only # -- Additional sensible rules ------------------------------------------------ # Enforce consistent heading style (ATX = # style, not underline style) From 3cf4fecc994eb2500bb53afe47bfd361b9ce84b5 Mon Sep 17 00:00:00 2001 From: Matthew Maclay Date: Mon, 30 Mar 2026 09:50:29 -0600 Subject: [PATCH 33/33] readthedocs python 311 --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 64ed8d7..a4b14fc 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -7,7 +7,7 @@ version: 2 build: os: "ubuntu-22.04" tools: - python: "3.10" + python: "3.11" jobs: post_create_environment: # Install poetry