项目结构 1.0.1

模板使用方法

这是一个关于如何在项目中使用此模板的简要指南。它尚未得到广泛测试。这样的测试是元测试，创建和支持它是无益的。报告您遇到的问题，或者最好是提交带有修正的PR。

1. 选择要使用的分支

   选择适合您的项目类型的分支

   • py:

     基本的Python发行版元数据和打包。

   • py-cli:

     前面提到的命令行控制台脚本（带有子命令）的样板。

   • docker:

     开发、最终用户或部署的Docker镜像。

   • py-docker:

     前面提到的Docker镜像，安装了Python包。

   • ci:

     前面提到的GitLab CI/CD管道，在CI中运行测试和代码风格检查，在CD中从 develop 和 main 发布。

   • py-ci:

     将 py-docker 和 ci 分支合并在一起。

   • py-ci-cli:

     前面所有内容的组合。

   使用前面的分支之一合并到您的项目中非常重要，而不是模板中的 develop 或 main 分支。模板开发者使用这些分支来测试发布过程。它们包含增加的版本、发布说明和其他发布工件，真实项目不应该将其合并到其代码或历史中。

2. 合并到您的项目

   如果您要开始一个全新的项目

   $ git clone --origin "template" --branch "${TEMPLATE_BRANCH:?}" \
   "https://gitlab.com/rpatterson/project-structure.git" "./foo-project"
   $ cd "./foo-project"
   $ git config remote.template.tagOpt --no-tags
   $ git remote add "origin" "git@gitlab.com:foo-username/foo-project.git"
   $ git switch -C "main" --track "origin/main"

   如果您要将合并到现有的项目中

   $ git remote add "template" \
   "https://gitlab.com/rpatterson/project-structure.git"
   $ git config remote.template.tagOpt --no-tags
   $ git merge --allow-unrelated-histories "template/${TEMPLATE_BRANCH:?}"

3. 重命名由项目名称派生的文件和目录

   $ git ls-files | grep -iE 'project.?structure'

4. 重命名项目名称和模板创建者身份字符串

   $ git grep -iE 'project.?structure|ross|Patterson'

5. 根据 # TEMPLATE: 注释进行修改

   这些部分需要开发者的注意和推理。请仔细阅读注释并遵循它们

   $ git grep "TEMPLATE"

最后，移除这个 模板使用 部分，并更新 ./README.rst 的其余部分以适应您的项目。当模板添加修复和功能时，将它们合并到您的项目中，并重复步骤 3–5。

此模板在推送 develop 分支时发布预发布版本，在推送 main 分支时发布最终版本。项目所有者可以决定在最终发布之前需要预发布的更改类型，以及直接进入最终发布的更改类型。例如，他们可以决定

• 将公共贡献合并到 develop 中。请参阅 贡献文档 [16] 了解公共贡献政策和工作流程的示例。

• 可选地，将最终发布中的错误修复提交到 main 分支的一个分支。通过通过所有测试和检查后，将其合并回 main 以直接发布最终版本。

• 可选地，也可以直接将安全更新版本升级合并到 main。

安装

本地安装或使用 Docker 容器镜像

$ pip3 install --user project-structure

$ docker compose up

$ docker pull "registry.gitlab.com/rpatterson/project-structure"
$ docker run --rm -it "registry.gitlab.com/rpatterson/project-structure" ...

使用方法

有关选项和参数的详细信息，请参阅命令行帮助

$ project-structure --help
usage: project-structure [-h]

project structure foundation or template, top-level package.

Pptional arguments:
  -h, --help  show this help message and exit

Docker容器镜像可以运行命令行脚本

$ docker compose run "project-structure" project-structure --help
usage: project-structure [-h]

Project structure foundation or template, top-level package.

optional arguments:
  -h, --help  show this help message and exit

贡献

GitLab托管此项目 [22] 并 将其镜像到GitHub [23] 但请使用GitLab来报告问题、提交拉取或合并请求以及任何其他开发或维护活动。有关如何开始开发的更多详细信息，请参阅 贡献文档 [16]。

动机

存在许多其他项目模板。为什么还要创建一个新的？我从1998年开始成为一名全栈Web开发者。我有足够的时间形成自己的很多观点。从一个模板中，我想要一个完整的工具集（例如测试覆盖率、代码检查、格式化、持续集成）。相反，我想要最小化的依赖关系、结构和超出完整工具集之外的意见（例如一些构建或任务系统、未使用的框架或库的结构）。我没有找到这样一个平衡的模板，所以我创建了它。

我还发现很难从其他模板中分辨出它们为什么做出这样的选择。因此，我还使用这个模板来尝试不同的选项，并亲自学习。您可以在提交历史中了解我的发现以及我做出选择的原因。

最重要的是，我从未找到一种令人满意的方法来随着时间的推移保持项目结构的更新。因此，主要的动机是提供一个上游远程模板，将结构更新合并到实际项目中，在其整个生命周期中。

参考文献