Adjust docs, add changelog

changelog/+devinit.added.md

@@ -0,0 +1 @@
+Added development environment initialization script to generated projects

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

changelog/+win.fixed.md

@@ -0,0 +1 @@
+Added test runs on macOS and Windows and fixed some issues on Windows

changelog/41.fixed.md

@@ -0,0 +1 @@
+Fixed unwanted regeneration of deleted boilerplate during updates

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

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
 

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"

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

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

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 %}

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"