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/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..6f1ac6e --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,69 @@ +name: Docs Build + +# 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] + +env: + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true + +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) + id: build + shell: bash + run: | + set -o pipefail + poetry run sphinx-build -W --keep-going -n \ + 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 "" + 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" diff --git a/.github/workflows/pr-triage.yml b/.github/workflows/pr-triage.yml new file mode 100644 index 0000000..caa9d3f --- /dev/null +++ b/.github/workflows/pr-triage.yml @@ -0,0 +1,56 @@ +name: PR Triage + +# 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: [opened, reopened, ready_for_review] + +permissions: + pull-requests: write + issues: write + +env: + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true + +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. + # 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: | + 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.', + }); diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index c1729b6..3a49d3f 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -1,13 +1,23 @@ 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] + +# 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 }}) runs-on: ${{ matrix.os }} strategy: + fail-fast: false matrix: os: [ubuntu-latest, macos-latest] python-version: ['3.10', '3.11'] @@ -16,12 +26,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 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 diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000..9e0e874 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,62 @@ +# 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) +# 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 + +# 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/.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..7dbd634 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,21 +1,86 @@ 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: + # --------------------------------------------------------------------------- + # 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) + # markdownlint-cli2 is the official CLI maintained by the markdownlint author (DavidAnson). + # --------------------------------------------------------------------------- + - repo: https://github.com/DavidAnson/markdownlint-cli2 + rev: v0.19.1 + hooks: + - 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] + + # --------------------------------------------------------------------------- + # 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, .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. + - --write-changes + # 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..64ed8d7 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -14,9 +14,9 @@ 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: - configuration: docs/source/conf.py \ No newline at end of file + configuration: docs/source/conf.py + fail_on_warning: true diff --git a/.yamllint.yaml b/.yamllint.yaml new file mode 100644 index 0000000..d2f5364 --- /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 + + # Do not require documents to start with --- (document-start rule disabled) + document-start: disable 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/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. 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. 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/conf.py b/docs/source/conf.py index c8a8be9..6548dcd 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 = { @@ -39,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') 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 4f50203..793e646 100644 --- a/docs/source/data_management/digital_object_identifiers.md +++ b/docs/source/data_management/digital_object_identifiers.md @@ -51,7 +51,8 @@ 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 +72,8 @@ 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 +81,8 @@ 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 +92,8 @@ 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. @@ -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/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 af80a50..85fe8b5 100644 --- a/docs/source/data_management/index.rst +++ b/docs/source/data_management/index.rst @@ -5,9 +5,10 @@ Data Management .. toctree:: :maxdepth: 1 + data_management file_formats/index metadata.md 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/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 6b6626c..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 @@ -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/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/beginner_guide_to_docker.md b/docs/source/workflows/docker/beginner_guide_to_docker.md index e26de31..6bc2af9 100644 --- a/docs/source/workflows/docker/beginner_guide_to_docker.md +++ b/docs/source/workflows/docker/beginner_guide_to_docker.md @@ -87,12 +87,12 @@ 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: -```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/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/docker/index.rst b/docs/source/workflows/docker/index.rst index 95356b1..f708a21 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 + running_docker_with_m1 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: 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..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 @@ -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 @@ -77,4 +77,4 @@ to your [ITGC](/pages/viewpage.action?pageId=139193455) 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/generative_ai_tools/index.rst b/docs/source/workflows/generative_ai_tools/index.rst index 8ffb425..d99e49b 100644 --- a/docs/source/workflows/generative_ai_tools/index.rst +++ b/docs/source/workflows/generative_ai_tools/index.rst @@ -4,4 +4,4 @@ Generative AI Tools .. toctree:: :maxdepth: 1 - generative_ai_tools_at_lasp \ No newline at end of file + generative_ai_tools_at_lasp diff --git a/docs/source/workflows/index.rst b/docs/source/workflows/index.rst index 7b7f3e6..5746c9b 100644 --- a/docs/source/workflows/index.rst +++ b/docs/source/workflows/index.rst @@ -7,4 +7,3 @@ Workflows docker/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 4c20208..0000000 --- a/docs/source/workflows/jenkins_job_builder/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -Jenkins Job Builder -=================== - -.. toctree:: - :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/code_of_conduct.md b/docs/source/workflows/open_source/code_of_conduct.md index 908d41e..3f96194 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 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/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 diff --git a/docs/source/workflows/open_source/pull_requests.md b/docs/source/workflows/open_source/pull_requests.md index 3e824f8..8cbfdb7 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. +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,52 +26,74 @@ 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. +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 +## During review 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 + manner 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. Be honest - if you disagree with someones comment, start a discussion on why that is the case +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 someone's 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. +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. diff --git a/pyproject.toml b/pyproject.toml index 64a3187..b081f7c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -37,4 +37,5 @@ homepage = "https://github.com/lasp/" repository = "https://github.com/lasp/developer-guide" [tool.codespell] -ignore-words-list = "nd, SORCE, sav" +# NOTE: These need to be added to .pre-commit-config.yaml to be ignored. +ignore-words-list = "nd,ND,SORCE,sav"