Merge branch 'docs/docker-best-practices' of https://github.com/gianf…

…a/poetry into docs/docker-best-practices

.cirrus.yml

@@ -1,35 +1,79 @@
-freebsd_instance:
-  image_family: freebsd-13-0
-  cpu: 1
-  memory: 4G
-
-test_task:
-  name: "Tests / FreeBSD / "
-  only_if: $CIRRUS_TAG == ''
-  skip: "!changesInclude('.cirrus.yml', 'poetry.lock', 'pyproject.toml', '**.json','**.py')"
+tests_task:
+  # We only use Cirrus CI for FreeBSD at present; the rest of the task will assume FreeBSD.
+  freebsd_instance:
+    image_family: freebsd-14-0
+    # Cirrus has a concurrency limit of 8 vCPUs for FreeBSD. Allow executing 4 tasks in parallel.
+    cpu: 2
+    memory: 2G
+
   env:
     matrix:
-      - PYTHON: python3.7
       - PYTHON: python3.8
+        PYTHON_VERSION: 3.8
+        PYTHON_PACKAGE: python38
+        SQLITE_PACKAGE: py38-sqlite3
       - PYTHON: python3.9
+        PYTHON_VERSION: 3.9
+        PYTHON_PACKAGE: python39
+        SQLITE_PACKAGE: py39-sqlite3
       - PYTHON: python3.10
-  pkg_script:
-    - PYPACKAGE=$(printf '%s' $PYTHON | tr -d '.')
-    - SQLPACKAGE=$(printf '%s-sqlite3' $PYPACKAGE | sed 's/thon//')
-    - pkg install -y git-lite curl $PYPACKAGE $SQLPACKAGE
-  pip_script:
-    - $PYTHON -m ensurepip
-    - $PYTHON -m pip --disable-pip-version-check install -U pip
-  env_script:
-    - echo "PATH=/.local/bin:${PATH}" >> $CIRRUS_ENV
-  poetry_script:
-    - curl -sL https://install.python-poetry.org | $PYTHON - -y
-    - poetry config virtualenvs.in-project true
-  test_script:
+        PYTHON_VERSION: 3.10
+        PYTHON_PACKAGE: python310
+        SQLITE_PACKAGE: py310-sqlite3
+      - PYTHON: python3.11
+        PYTHON_VERSION: 3.11
+        PYTHON_PACKAGE: python311
+        SQLITE_PACKAGE: py311-sqlite3
+      # FIXME: Python 3.12 is not available in Ports.
+      # - PYTHON: python3.12
+      #   PYTHON_VERSION: 3.12
+      #   PYTHON_PACKAGE: python312
+      #   SQLITE_PACKAGE: py312-sqlite3
+    # FIXME: use pipx for install. pipx is currently broken in Ports.
+    POETRY_HOME: /opt/poetry
+    # SHELL is not set by default, and we have tests that depend on it.
+    SHELL: sh
+
+  bootstrap_poetry_script:
+    - pkg install -y git $PYTHON_PACKAGE $SQLITE_PACKAGE
+    - $PYTHON -m venv $POETRY_HOME
+    - $POETRY_HOME/bin/pip install poetry
+    - echo "PATH=${POETRY_HOME}/bin:${PATH}" >> $CIRRUS_ENV
+
+  setup_environment_script:
+    # TODO: caching
     - poetry install
-    - poetry run pytest -q --junitxml=junit.xml tests
-  on_failure:
-    annotate_failure_artifacts:
-      path: junit.xml
-      format: junit
-      type: text/xml
+    - poetry env info
+    - poetry show
+
+  matrix:
+    - alias: pytest
+      name: "Tests / FreeBSD (Python ${PYTHON_VERSION}) / pytest"
+      skip: "!changesInclude('.cirrus.yml', 'poetry.lock', 'pyproject.toml', 'src/**.py', 'tests/**')"
+      pytest_script: poetry run pytest --integration -v --junitxml=junit.xml
+      on_failure:
+        annotate_failure_artifacts:
+          path: junit.xml
+          format: junit
+          type: text/xml
+
+    # TODO: caching
+    - alias: mypy
+      name: "Tests / FreeBSD (Python ${PYTHON_VERSION}) / mypy"
+      skip: "!changesInclude('.cirrus.yml', 'poetry.lock', 'pyproject.toml', 'src/**.py', 'tests/**')"
+      mypy_script: poetry run mypy
+
+status_task:
+  name: "Tests / FreeBSD Status"
+
+  depends_on:
+    - pytest
+    - mypy
+
+  container:
+    image: alpine:latest
+    cpu: 0.5
+    memory: 512M
+
+  # No-op the clone.
+  clone_script: true

.gitattributes

@@ -0,0 +1,2 @@
+# Do not mess with line endings in metadata files or the hash will be wrong.
+*.metadata binary

.github/ISSUE_TEMPLATE/---bug-report.yml

@@ -0,0 +1,96 @@
+name: "\U0001F41E Bug Report"
+labels: ["kind/bug", "status/triage"]
+description: "Poetry not working the way it is documented?"
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to file a complete bug report.
+
+        Before submitting your issue, please review the [Before submitting a bug report](https://python-poetry.org/docs/contributing/#before-submitting-a-bug-report) section of our documentation.
+
+  - type: textarea
+    attributes:
+      label: Description
+      description: |
+        Please describe what happened, with as much pertinent information as you can. Feel free to use markdown syntax.
+
+        Also, ensure that the issue is not already fixed in the [latest](https://github.com/python-poetry/poetry/releases/latest) Poetry release.
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Workarounds
+      description: |
+        Is there a mitigation or workaround that allows users to avoid the issue today?
+    validations:
+      required: true
+
+  - type: dropdown
+    attributes:
+      label: Poetry Installation Method
+      description: |
+        How did you install Poetry?
+      options:
+        - "pipx"
+        - "install.python-poetry.org"
+        - "system package manager (eg: dnf, apt etc.)"
+        - "pip"
+        - "other"
+    validations:
+      required: true
+
+  - type: input
+    attributes:
+      label: Operating System
+      description: |
+        What Operating System are you using?
+      placeholder: "Fedora 39"
+    validations:
+      required: true
+
+  - type: input
+    attributes:
+      label: Poetry Version
+      description: |
+        Please attach output from `poetry --version`
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Poetry Configuration
+      description: |
+        Please attach output from `poetry config --list`
+      render: 'bash session'
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Python Sysconfig
+      description: |
+        Please attach output from `python -m sysconfig`
+      render: 'bash session'
+    validations:
+      required: false
+
+  - type: textarea
+    attributes:
+      label: Example pyproject.toml
+      description: |
+        Please provide an example `pyproject.toml` demonstrating the issue.
+      render: 'TOML'
+    validations:
+      required: false
+
+  - type: textarea
+    attributes:
+      label: Poetry Runtime Logs
+      description: |
+        Please attach logs from the failing command using `poetry -vvv <command>`
+      render: 'bash session'
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/---documentation.yml

@@ -0,0 +1,46 @@
+name: "\U0001F4DA Documentation Issue"
+labels: ["area/docs", "status/triage"]
+description: "Did you find errors, omissions, or anything unintelligible in the documentation?"
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to file a complete bug report.
+
+        Before submitting your issue, please review the [Suggesting enhancements](https://python-poetry.org/docs/contributing/#suggesting-enhancements) section of our documentation.
+
+        Please also confirm the following:
+        - You have searched the [issues](https://github.com/python-poetry/poetry/issues) of this repository and believe that this is not a duplicate.
+        - You have searched the [FAQ](https://python-poetry.org/docs/faq/) and general [documentation](https://python-poetry.org/docs/) and believe that your question is not already covered.
+
+  - type: dropdown
+    attributes:
+      label: Issue Kind
+      description: |
+        What best describes the issue?
+      options:
+        - "Improving documentation"
+        - "Missing documentation"
+        - "Error in existing documentation"
+        - "Unclear documentation"
+        - "Other concerns with documentation"
+    validations:
+      required: true
+
+  - type: input
+    attributes:
+      label: Existing Link
+      description: |
+        If the documentation in question exists, please provide a link to it.
+      placeholder: "https://python-poetry.org/docs/dependency-specification/#version-constraints"
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Description
+      description: |
+        Please describe the feature, with as much pertinent information as you can. Feel free to use markdown syntax.
+    validations:
+      required: true