From c0e3c871a281afa2b989dd292cbba8797d4ee3cc Mon Sep 17 00:00:00 2001 From: jeanluc Date: Sun, 22 Sep 2024 09:53:17 +0200 Subject: [PATCH] Adjust docs, add changelog --- changelog/+devinit.added.md | 1 + changelog/+envrc.added.md | 1 + changelog/+win.fixed.md | 1 + changelog/41.fixed.md | 1 + changelog/45.added.md | 1 + copier.yml | 9 ++++++++- docs/topics/creation.md | 23 +++++++++++++++-------- docs/topics/documenting/building.md | 2 +- docs/topics/testing/running.md | 2 +- project/README.md.j2 | 15 ++++++++++++++- pyproject.toml | 2 +- 11 files changed, 45 insertions(+), 13 deletions(-) create mode 100644 changelog/+devinit.added.md create mode 100644 changelog/+envrc.added.md create mode 100644 changelog/+win.fixed.md create mode 100644 changelog/41.fixed.md create mode 100644 changelog/45.added.md diff --git a/changelog/+devinit.added.md b/changelog/+devinit.added.md new file mode 100644 index 0000000..f996bde --- /dev/null +++ b/changelog/+devinit.added.md @@ -0,0 +1 @@ +Added development environment initialization script to generated projects diff --git a/changelog/+envrc.added.md b/changelog/+envrc.added.md new file mode 100644 index 0000000..0bbbd62 --- /dev/null +++ b/changelog/+envrc.added.md @@ -0,0 +1 @@ +Added a `.envrc` for direnv that runs the new initialization script, ensuring that development environments are present and in sync for all developers diff --git a/changelog/+win.fixed.md b/changelog/+win.fixed.md new file mode 100644 index 0000000..763f2ad --- /dev/null +++ b/changelog/+win.fixed.md @@ -0,0 +1 @@ +Added test runs on macOS and Windows and fixed some issues on Windows diff --git a/changelog/41.fixed.md b/changelog/41.fixed.md new file mode 100644 index 0000000..6e570a2 --- /dev/null +++ b/changelog/41.fixed.md @@ -0,0 +1 @@ +Fixed unwanted regeneration of deleted boilerplate during updates diff --git a/changelog/45.added.md b/changelog/45.added.md new file mode 100644 index 0000000..f13ff7c --- /dev/null +++ b/changelog/45.added.md @@ -0,0 +1 @@ +Automated most post-copy/update tasks like repo initialization, dev env setup and pre-commit installation and running diff --git a/copier.yml b/copier.yml index 83c349a..84f8975 100644 --- a/copier.yml +++ b/copier.yml @@ -368,7 +368,14 @@ _message_after_copy: | Your Salt extension project "{{ project_name_full }}" has been created successfully! 🎉 - You should continue with the first steps documented here: + At this point, your development environment should be ready to go. + If you have installed `direnv`, it can be activated automatically, + otherwise you need to source the Python virtual environment manually: + + $ cd '{{ _copier_conf.dst_path }}' + $ source .venv/bin/activate + + If you encounter any problems, try the manual steps documented here: ▶ https://salt-extensions.github.io/salt-extension-copier/topics/creation.html#first-steps diff --git a/docs/topics/creation.md b/docs/topics/creation.md index b1f2637..a44f8d7 100644 --- a/docs/topics/creation.md +++ b/docs/topics/creation.md @@ -30,19 +30,26 @@ If hosting the repository outside the organization, you can choose your provider (first-steps-target)= ## First steps +Before hacking away on your new Salt extension, you need to initialize a Git repository and set up a development environment. -:::{important} -Usually not needed anymore. Copier attempts to run all of the below steps for you, with the exception of committing. +Contributors to existing Salt extension projects need to do the latter after cloning. -When the automation fails for some reason or you skipped it, ensure you execute the following steps manually. -::: +### Automatic +This process is automated completely in the following cases: + +* For maintainers: When creating/updating a project via Copier, unless `SKIP_INIT_MIGRATE=1` was set in the environment (repo initialization + dev env setup + pre-commit hook installation + running pre-commit). +* For all developers: When `direnv` is installed and the project's `.envrc` is allowed to run (dev env setup + pre-commit hook installation). :::{hint} -If you want to skip this automation, set `SKIP_INIT_MIGRATE=1` in the Copier environment. -::: +Without `direnv`, you can still call the automation script manually after entering the project root directory: -To finalize your project setup, ensure you initialize the Git repository and Python virtual environment and install and run the `pre-commit` hooks. +```bash +python3 tools/initialize.py +source .venv/bin/activate +``` +::: +### Manual ### Initialize the repository ```bash git init -b main @@ -69,7 +76,7 @@ python -m pre_commit install --install-hooks This ensures `pre-commit` runs before each commit. It autoformats and lints your code and ensures the presence of necessary documentation files. To skip these checks temporarily, use `git commit --no-verify`. -### First commit +## First commit ```bash git add . git commit -m "Initial extension layout" diff --git a/docs/topics/documenting/building.md b/docs/topics/documenting/building.md index f71b07b..7db819a 100644 --- a/docs/topics/documenting/building.md +++ b/docs/topics/documenting/building.md @@ -2,7 +2,7 @@ # Building documentation :::{important} -Ensure `nox` is installed. If you followed the [first steps](first-steps-target) or Copier executed the steps automatically, you should be all set. +Ensure `nox` is installed. If you executed the [first steps](first-steps-target) in some way, you should be all set. ::: ## Prerequisites diff --git a/docs/topics/testing/running.md b/docs/topics/testing/running.md index b986dbc..5623aa6 100644 --- a/docs/topics/testing/running.md +++ b/docs/topics/testing/running.md @@ -2,7 +2,7 @@ # Running the test suite :::{important} -Ensure `nox` is installed. If you followed the [first steps](first-steps-target) or Copier executed the steps automatically, you should be ready to go. +Ensure `nox` is installed. If you executed the [first steps](first-steps-target) in some way, you should be ready to go. ::: ## Basic diff --git a/project/README.md.j2 b/project/README.md.j2 index de9f763..fc88989 100644 --- a/project/README.md.j2 +++ b/project/README.md.j2 @@ -36,7 +36,19 @@ git clone --origin upstream {{ source_url | replace("https://", "git@") | replac cd {{ project_name_full }} ``` -Then follow the [first steps][first-steps], skipping the repository initialization and first commit. +#### Automatic +If you have installed [direnv][direnv], allowing the project's `.envrc` ensures +a proper development environment is present and the virtual environment is active. + +Without `direnv`, you can still run the automation explicitly: + +```bash +python3 tools/initialize.py +source .venv/bin/activate +``` + +#### Manual +Please follow the [first steps][first-steps], skipping the repository initialization and first commit. {%- if "github.com" in source_url %} @@ -93,6 +105,7 @@ appreciate every contribution! [rendering-docs]: https://salt-extensions.github.io/salt-extension-copier/topics/documenting/building.html [first-steps]: https://salt-extensions.github.io/salt-extension-copier/topics/creation.html#initialize-the-python-virtual-environment [submitting-pr]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork +[direnv]: https://direnv.net {%- if tracker_url %} [issues]: {{ tracker_url }} {%- endif %} diff --git a/pyproject.toml b/pyproject.toml index 3918e42..0631354 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -17,7 +17,7 @@ directory = "changelog/" start_string = "# Changelog\n" underlines = ["", "", ""] title_format = "## {version} ({project_date})" -issue_format = "[#{issue}](https://github.com/salt-extensions/salt-extension/copier/issues/{issue})" +issue_format = "[#{issue}](https://github.com/salt-extensions/salt-extension-copier/issues/{issue})" [[tool.towncrier.type]] directory = "removed"