last amendments

docs/effective-volto/addons/use-repo-addon.md

@@ -25,26 +25,18 @@ By doing this, you can develop both the project and the add-on product as if
 they were both part of the current codebase. Once the add-on development is
 done, you can publish the package to an npm repository.
 
-```shell
-yarn add mrs-developer
-```
+`mrs-developer` is included and installed by default when you generate a project with the generator.
+There is a `Makefile` command that installs the configuration of `mrs.developer.json` in your project.
 
-Then, in `package.json`:
-
-```json hl_lines="2"
-  "scripts": {
-    "develop": "missdev --config=jsconfig.json --output=addons",
-  }
+```shell
+make install
 ```
 
-We can configure `mrs-developer` to use any directory that you want. Here we
-are telling it to create the directory `src/addons` and put the packages
-managed by `mrs-developer` inside.
-
 ## mrs.developer.json
 
 This is the configuration file that instructs `mrs-developer` from where it has
-to pull the packages. So, create `mrs.developer.json` and add:
+to pull the packages.
+The generator includes an empty one for you, edit `mrs.developer.json` and add:
 
 ```json
 {
@@ -59,13 +51,13 @@ to pull the packages. So, create `mrs.developer.json` and add:
 Then run:
 
 ```bash
-yarn develop
+make install
 ```
 
 Now the addon is found in `src/addons/`.
 
 ```{note}
-`package` property is optional, set it up only if your package has a scope.
+`package` property is optional, set it up only if your package has a scope (namespace).
 `src` is required if the content of your addon is located in the `src`
 directory (but, as that is the convention recommended for all Volto add-on
 packages, you will always include it)
@@ -76,7 +68,7 @@ If you want to know more about `mrs-developer` config options, please refer to
 
 ## tsconfig.json / jsconfig.json
 
-`mrs-developer` automatically creates this file for you, but if you choose not
+`mrs-developer` automatically manages the contents of this file for you, but if you choose not
 to use mrs-developer, you'll have to add something like this to your
 `tsconfig.json` or `jsconfig.json` file in the Volto project root:
 
@@ -93,6 +85,8 @@ to use mrs-developer, you'll have to add something like this to your
 }
 ```
 
+This is required so the project "knows" about your package in development and the imports to work correctly.
+
 ```{warning}
 Please note that both `paths` and `baseUrl` are required to match your
 project layout.
@@ -120,7 +114,7 @@ you can set its developing status by adding a `develop` key:
 }
 ```
 
-You can toggle that key to `false` and run `yarn develop` again.
+You can toggle that key to `false` and run `make install` again.
 
 ### Addon dependencies, yarn workspaces
 
@@ -145,3 +139,4 @@ It is common practice to use a star glob pattern for the workspaces:
 If you do this, make sure to always cleanup the `src/addons` folder whenever
 you toggle the development status of an addon, as the existence of the addon
 folder under the `src/addons` will still influence yarn.
+Running `make install` again will do the trick and remove the not required anymore package.

docs/effective-volto/architecture/bootstrap-volto.md

@@ -172,7 +172,7 @@ Use the project generator helper utility.
     yo @plone/volto --help
     ```
 
-    or take a look at the [README](https://github.com/plone/volto/blob/master/packages/generator-volto/README.md) for more information.
+    or take a look at the [README](https://github.com/plone/volto/blob/main/packages/generator-volto/README.md) for more information.
     ````
 
 3.  Change directory to the newly created folder `myvoltoapp` (or the one you've chosen):

docs/effective-volto/backend/plone-restapi-endpoints.md

@@ -12,12 +12,17 @@ myst:
 Volto comunicates with the Plone backend via the so-called "endpoints", which
 care REST API services exposed by plone.restapi.
 
-You communicate with the REST API service using `application/json` ACCEPT header:
+You communicate with the REST API service using `application/json` ACCEPT header.
+You can also use the `++api++` traversal which does not need the header:
 
 ```bash
 curl -H "Accept: application/json" http://localhost:8080/Plone/mycontent
 ```
 
+```bash
+curl http://localhost:8080/Plone/++api++/mycontent
+```
+
 Unless you found a bug in code, the response from the server is JSON content (using the [JSONSchema][1] format).
 
 ```

docs/effective-volto/deployment/docker.md

@@ -16,7 +16,7 @@ It is recommended that you follow the best practices explained in the "Installin
 
 You'll find in the Volto repository a simple `docker-compose` example:
 
-https://github.com/plone/volto/blob/master/docker-compose.yml
+https://github.com/plone/volto/blob/main/docker-compose.yml
 
 ```shell
 docker-compose -f <following_snippet.yml> up

docs/effective-volto/deployment/releaseit.md

@@ -19,7 +19,7 @@ If you are familiarized with `zest.releaser` in the Python packaging world, this
 
 ## Basic configuration
 
-In your `package.json`:
+In your `package.json` or in `.release-it.json`:
 
 ```json
   "release-it": {
@@ -44,6 +44,74 @@ In your `package.json`:
   },
 ```
 
+```{note}
+We also use the `changelogupdater` command from `@plone/scripts`. See {ref}`plone-scripts-label` for more information.
+```
+
+## Using it along with `towncrier` in add-ons
+
+```json
+{
+  "hooks": {
+    "after:bump": "pipx run towncrier build --draft --yes --version ${version} > .changelog.draft && pipx run towncrier build --yes --version ${version}",
+    "after:release": "rm .changelog.draft"
+  },
+  "git": {
+    "changelog": "pipx run towncrier build --draft --yes --version 0.0.0",
+    "requireUpstream": false,
+    "requireCleanWorkingDir": false,
+    "commitMessage": "Release ${version}",
+    "tagName": "${version}",
+    "tagAnnotation": "Release ${version}"
+  },
+  "github": {
+    "release": true,
+    "releaseName": "${version}",
+    "releaseNotes": "cat .changelog.draft"
+  }
+}
+```
+
+You need to setup an empty `news` folder and a `towncrier.toml`:
+
+```ini
+[tool.towncrier]
+filename = "CHANGELOG.md"
+directory = "news/"
+title_format = "## {version} ({project_date})"
+underlines = ["", "", ""]
+template = "packages/scripts/templates/towncrier_template.jinja"
+start_string = "<!-- towncrier release notes start -->\n"
+issue_format = "[#{issue}](https://github.com/plone/volto/issues/{issue})"
+
+[[tool.towncrier.type]]
+directory = "breaking"
+name = "Breaking"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "feature"
+name = "Feature"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "bugfix"
+name = "Bugfix"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "internal"
+name = "Internal"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "documentation"
+name = "Documentation"
+showcontent = true
+```
+
+and make your add-on rely on `@plone/scripts` (which should already have) if your add-on has been created using the generator.
+
 ```{note}
 You can refer to the `release-it` documentation for further information:
 https://www.npmjs.com/package/release-it
@@ -54,5 +122,3 @@ It also has default named hooks that do common tasks like creating a Release on
 Hook into a state in the lifecycle is easy, you can issue several commands that will be added to the default defined ones (https://github.com/release-it/release-it/blob/HEAD/config/release-it.json).
 You can modify the default ones to adjust to your requirements.
 eg. in the example, we hook into the `before:bump`, `after:bump` and `after:release` to issue custom commands accordingly to each state of the release.
-
-We also use the `changelogupdater` command from `@plone/scripts`. See {ref}`plone-scripts-label` for more information.

docs/effective-volto/deployment/seamlessmode.md

@@ -7,7 +7,7 @@ myst:
     "keywords": "Volto, Plone, frontend, React, Seamless, mode"
 ---
 
-# Seamless mode
+# Recommended deployment schema (aka Seamless mode)
 
 In any Plone + Volto deployment, we have the following services:
 

docs/effective-volto/deployment/simple.md

@@ -7,7 +7,7 @@ myst:
     "keywords": "Volto, Plone, frontend, React, deployment"
 ---
 
-# Old (pre-seamless mode) deployment
+# [DEPRECATED] Old (pre-seamless mode) deployment
 
 Volto is a Node application that runs on your machine/server and listens to a port. Once you are ready to deploy it, you should build it running:
 

docs/voltoaddons/02-block-edit.md

@@ -260,7 +260,7 @@ The reducer code looks scary, but it shouldn't be. To understand it, you need
 to know:
 
 - In Volto, all actions that have a `request` field are treated as network
-  requests, and they will be processed by the [API middleware](https://github.com/plone/volto/blob/master/src/middleware/api.js).
+  requests, and they will be processed by the [API middleware](https://github.com/plone/volto/blob/main/src/middleware/api.js).
 - That middleware will then trigger several new actions, derived from the main
   function and prefixed with its name, either `PENDING`, `SUCCESS`, or `FAIL`.
 - For each of these new actions, we will reduce the state of the store to

docs/voltoaddons/04-block-edit-options.md

@@ -438,5 +438,5 @@ export default withBlockDataSource({
 })(DataTableEdit);
 ```
 
-[field.jsx]: https://github.com/plone/volto/blob/master/src/components/manage/Form/Field.jsx
-[Volto's widget documentation]: https://github.com/plone/volto/blob/master/docs/source/recipes/widget.md
+[field.jsx]: https://github.com/plone/volto/blob/main/src/components/manage/Form/Field.jsx
+[Volto's widget documentation]: https://github.com/plone/volto/blob/main/docs/source/recipes/widget.md