docs: use one volume-naming rule across the Docker volume docs

Đang mở Phù hợp với người mới
  • Có gì không ổn?
#460 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
68/100
Loại issue
Tài liệu
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
docker, docker-compose
Lĩnh vực
documentation

Hướng nghiên cứu

Đọc ba tệp được nêu: docs/DOCKER_CONFIGURATION.md, docs/VOLUMES.md và docs/VOLUME_TESTING.md, sau đó so sánh tên volume trong đó với docker-compose.yml, docker-compose.prod.yml và docker-compose.test.yml. Chỉ cập nhật các tài liệu đó để các khóa Compose được xác định là khóa, lệnh Docker sử dụng tên volume có tiền tố dự án, có cảnh báo về sao lưu và khôi phục, đồng thời sửa các tên và ngày tháng lỗi thời trong ví dụ. Không cần chạy kiểm thử vì đây chỉ là thay đổi tài liệu.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

Follow-up to #444 (merged in #459). Part of #403. Docs only: branch from main and open the PR against main.

Problem

#444 documented that the real Docker volume names are <project>_<key> (for example taskflowapi_taskflow-data on the owner's machine). The other volume docs still use bare compose keys or hand-made names, so some commands in them do not match any real volume. The implementation notes on #444 listed three of these; checking them against main found more.

  1. docs/DOCKER_CONFIGURATION.md, "Volume Mounts" (about line 127). "Both environments use named Docker volumes" lists taskflow-data and taskflow-logs. The local prod harness (docker-compose.prod.yml) uses the keys taskflow-data-prod and taskflow-logs-prod, and every real name carries the project prefix. The new "Compose Project Name" section right after the table explains the prefix, so the table now sits above its own correction.
  2. docs/VOLUMES.md mixes three naming schemes.
    • Bare keys (taskflow-data, taskflow-logs) in docker volume inspect and docker volume rm (about lines 140, 250, 257).
    • Hand-made taskflow-prod-data and taskflow-prod-logs in the manual prod example (about lines 175-214).
    • taskflow-data-prod and taskflow-logs-prod for the compose harness (about line 231).
    • Data-safety point: the backup and restore commands (about lines 275-310) run docker run -v taskflow-data:/data .... Docker creates a named volume that does not exist, so on a machine where the real volume is <project>_taskflow-data this command silently mounts a new empty volume. A backup would contain nothing, and a restore would write into a stray volume.
  3. docs/VOLUME_TESTING.md. The sample docker volume inspect output has a CreatedAt of 2024-11-02T... (stale), and its commands hard-code the owner's project name taskflowapi_ (about lines 34-55, 349 and 368). #444 chose to name no machine-specific project in DOCKER_CONFIGURATION.md.

Change

Edit docs/DOCKER_CONFIGURATION.md, docs/VOLUMES.md and docs/VOLUME_TESTING.md only. One naming rule, applied everywhere:

  • When describing compose configuration, use the compose key (taskflow-data), and say it is a key.
  • In any docker volume ... or docker run -v ... command, use <project>_<key> with <project> as a placeholder, and point to the "Compose Project Name" section and docker volume ls --filter name=taskflow for finding the real name.
  • Name the prod harness keys correctly (taskflow-data-prod, taskflow-logs-prod). For the manual docker volume create example, either keep its own names with a sentence saying it is separate from the harness, or switch it to the harness names; pick one and say which.
  • Fix the stale CreatedAt sample, and replace the hard-coded taskflowapi_ in VOLUME_TESTING.md.
  • Put a one-line warning by the backup and restore commands: use the real, prefixed volume name, because a wrong name creates an empty volume.
  • Check each command against docker-compose.yml, docker-compose.prod.yml and docker-compose.test.yml (read-only; docker compose config --volumes is fine). Do not run any command that removes or creates a volume.

Acceptance criteria

  1. The "Volume Mounts" table in DOCKER_CONFIGURATION.md no longer presents bare keys as the Docker volume names, and names the prod harness keys correctly.
  2. VOLUMES.md uses one consistent naming rule; its inspect, remove, backup and restore commands use the project-prefixed name, with the backup and restore warning.
  3. VOLUME_TESTING.md has no stale 2024-11-02 sample and no hard-coded taskflowapi_.
  4. No compose file, .env or volume changes, and nothing suggests deleting a volume. The owner's decision on #444 stands: the taskflow_* volumes are kept.
  5. Only the three docs files change.

Tests

No tests apply (docs only). Say so in the PR body.

Out of scope

  • Adding name: to the compose files (a later option, documented in #459).
  • The live API port (8081 in the doc, 8080 in the gitignored local override) and the bare docker compose up/down -v in ci.yml, which is safe today because the runner has no .env.
  • The test-stack text already fixed in #459.
Ngôn ngữ chính
C#
Star
1
Fork
0
Merge trung bình
2 giờ 2 phút
Pull request đã merge (30 ngày)
98

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của nevridge/TaskFlow

Tất cả issue của nevridge/TaskFlow

Issue tương tự

Thêm issue về C#

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.