Skip to content

Commit 8ca912c

Browse files
davisaglidavisagli
authored
Merge pull request #2073 from plone/uv-managed-stevepiercy
Build upon #2702
2 parents f919508 + bde905b commit 8ca912c

1 file changed

Lines changed: 94 additions & 96 deletions

File tree

‎docs/admin-guide/add-ons.md‎

Lines changed: 94 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -18,92 +18,48 @@ The Volto frontend has its own system of add-ons using Node.js packages.
1818
See {doc}`/volto/development/add-ons/index`.
1919
```
2020

21-
## Install an add-on from PyPI
22-
23-
For instructions to install an add-on that is released on {term}`PyPI`, select the tab below according to your Python package manager.
24-
25-
```{tip}
26-
Select the tab for uv if you have a project that was created using Cookieplone, and you have `managed = true` set in the `[tool.uv]` section of the file {file}`backend/pyproject.toml`.
27-
Select the tab for pip if you have a project that was created using Cookieplone that does not have this setting.
28-
```
29-
30-
`````{tab-set}
31-
32-
````{tab-item} uv
33-
34-
Add the name of your add-on in the file {file}`backend/pyproject.toml` in the section `dependencies`.
35-
This example adds [`collective.easyform`](https://pypi.org/project/collective.easyform/).
21+
(install-an-add-on-from-pypi-label)=
3622

37-
```{code-block} toml
38-
:emphasize-lines: 6
39-
dependencies = [
40-
"Products.CMFPlone==6.1.1",
41-
"plone.api",
42-
"plone.classicui",
43-
"plone.app.caching",
44-
"collective.easyform==4.4.0",
45-
]
46-
```
23+
## Install an add-on from PyPI
4724

48-
```{tip}
49-
Including the add-on version, or "pinning a version", ensures that it won't unintentionally get upgraded in the future.
50-
```
25+
This section describes how to install an add-on that is released on {term}`PyPI`.
5126

52-
Also add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` to make sure its configuration will be loaded.
5327

54-
```yaml
55-
default_context:
56-
zcml_package_includes: project_title, collective.easyform
57-
```
28+
(configure-add-on-installation-pypi-label)=
5829

59-
Stop the backend with {kbd}`ctrl-c`.
30+
### Configure add-on installation
6031

61-
To actually download and install the new add-on, run the following command.
32+
First, configure your project according to the instructions in the tabbed interface below.
33+
Select the tab according to the method you used to create your project.
6234

63-
```shell
64-
make backend-build
65-
```
66-
67-
````
68-
69-
````{tab-item} pip
35+
`````{tab-set}
36+
````{tab-item} Cookieplone
37+
:sync: cookieplone
7038
7139
Add the name of your add-on in the file {file}`backend/pyproject.toml` in the section `dependencies`.
7240
This example adds [`collective.easyform`](https://pypi.org/project/collective.easyform/).
7341
7442
```{code-block} toml
7543
:emphasize-lines: 6
7644
dependencies = [
77-
"Products.CMFPlone==6.1.1",
45+
"Products.CMFPlone==6.1.4",
7846
"plone.api",
7947
"plone.classicui",
8048
"plone.app.caching",
81-
"collective.easyform==4.4.0",
49+
"collective.easyform==4.5.1",
8250
]
8351
```
8452
85-
```{tip}
86-
Including the add-on version, or "pinning a version", ensures that it won't unintentionally get upgraded in the future.
87-
```
88-
89-
Also add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` to make sure its configuration will be loaded.
53+
To configure the add-on to load, in the file {file}`backend/instance.yaml`, under the key `default_context`, for the key `zcml_package_includes`, set its value to the add-on's name.
9054
9155
```yaml
9256
default_context:
9357
zcml_package_includes: project_title, collective.easyform
9458
```
95-
96-
Stop the backend with {kbd}`ctrl-c`.
97-
98-
To actually download and install the new add-on, run the following command.
99-
100-
```shell
101-
make backend-build
102-
```
103-
10459
````
10560
10661
````{tab-item} Buildout
62+
:sync: buildout
10763
10864
Update the file {file}`buildout.cfg`.
10965
This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
@@ -125,24 +81,46 @@ eggs =
12581
collective.easyform
12682
12783
[versions]
128-
collective.easyform = 4.2.1
84+
collective.easyform = 4.5.1
12985
```
86+
````
87+
`````
13088

13189
```{tip}
132-
Including the add-on version, or "pinning a version", ensures that it won't unintentionally get upgraded in the future.
90+
You can control which version of an add-on to install through "version pinning."
91+
92+
- Specify the add-on version to avoid its unintentional upgrade.
93+
- Leave it off to always install the latest version.
13394
```
13495

96+
97+
(install-the-add-on-pypi-label)=
98+
99+
### Install the add-on
100+
101+
Stop the backend with {kbd}`ctrl-c`.
102+
135103
To actually download and install the new add-on, run the following command.
136104

105+
`````{tab-set}
106+
````{tab-item} Cookieplone
107+
:sync: cookieplone
108+
137109
```shell
138-
bin/buildout -N
110+
make backend-build
139111
```
140-
141112
````
142113
114+
````{tab-item} Buildout
115+
:sync: buildout
116+
117+
```shell
118+
bin/buildout -N
119+
```
120+
````
143121
`````
144122

145-
Now restart the backend.
123+
Next, restart the backend.
146124

147125
```{seealso}
148126
{doc}`run-plone`
@@ -159,18 +137,26 @@ At the bottom of the page, you should see the heading {guilabel}`Add-on Configur
159137

160138
## Install an add-on from source
161139

162-
An unreleased add-on can be installed from a source control system such as GitHub.
140+
This section describes how to install an unreleased add-on from a source control system, such as GitHub.
141+
142+
143+
(configure-add-on-installation-source-label)=
144+
145+
### Configure add-on installation
163146

164-
For instructions to install an add-on that is released on {term}`PyPI`, select the tab below according to your Python package manager.
147+
First, configure your project according to the instructions in the tabbed interface below.
148+
Select the tab according to your Python package manager.
165149

166150
```{tip}
167-
Select the tab for uv if you have a project that was created using Cookieplone, and you have `managed = true` set in the `[tool.uv]` section of the file {file}`backend/pyproject.toml`.
168-
Select the tab for pip if you have a project that was created using Cookieplone that does not have this setting.
151+
For projects created with Cookieplone, select either the tab labeled:
152+
153+
- {guilabel}`uv` if the file {file}`backend/pyproject.toml`, under the table `[tool.uv]` has the setting of `managed = true`
154+
- {guilabel}`pip` if your project doesn't have this setting
169155
```
170156

171157
`````{tab-set}
172-
173158
````{tab-item} uv
159+
:sync: uv
174160
175161
Clone the repository into a local directory.
176162
This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
@@ -186,43 +172,32 @@ cd backend
186172
uv add --editable ../collective.easyform
187173
```
188174
189-
```{note}
190-
When installing an add-on from source, it's best not to pin a version.
191-
This way you always get the version that's currently available in the source control system.
192-
```
193-
194-
Next add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` so that its configuration will load.
175+
To configure the add-on to load, in the file {file}`backend/instance.yaml`, under the key `default_context`, for the key `zcml_package_includes`, set its value to the add-on's name.
195176
196177
```yaml
197178
default_context:
198179
zcml_package_includes: project_title, collective.easyform
199180
```
200-
201-
Stop the backend with {kbd}`ctrl-c`.
202181
````
203182
204183
````{tab-item} pip
184+
:sync: pip
205185
206186
Add the name of your add-on in the file {file}`backend/pyproject.toml` in the section `dependencies`.
207187
This example adds [`collective.easyform`](https://pypi.org/project/collective.easyform/).
208188
209189
```{code-block} toml
210190
:emphasize-lines: 6
211191
dependencies = [
212-
"Products.CMFPlone==6.1.1",
192+
"Products.CMFPlone==6.1.4",
213193
"plone.api",
214194
"plone.classicui",
215195
"plone.app.caching",
216196
"collective.easyform",
217197
]
218198
```
219199
220-
```{note}
221-
When installing an add-on from source, it's best not to pin a version.
222-
This way you always get the version that's currently available in the source control system.
223-
```
224-
225-
Next add the add-on to `zcml_package_includes` in the file {file}`backend/instance.yaml` so that its configuration will load.
200+
To configure the add-on to load, in the file {file}`backend/instance.yaml`, under the key `default_context`, for the key `zcml_package_includes`, set its value to the add-on's name.
226201
227202
```yaml
228203
default_context:
@@ -242,18 +217,10 @@ extras=test
242217
The {file}`mx.ini` file configures a tool called {term}`mxdev`.
243218
For an explanation of why Plone uses `mxdev`, see {ref}`manage-packages-mxdev-label`.
244219
```
245-
246-
Stop the backend with {kbd}`ctrl-c`.
247-
248-
To actually download and install the new add-on, run the following command.
249-
250-
```shell
251-
make backend-build
252-
```
253-
254220
````
255221
256222
````{tab-item} Buildout
223+
:sync: buildout
257224
258225
Update the file {file}`buildout.cfg`.
259226
This example uses [`collective.easyform`](https://pypi.org/project/collective.easyform/).
@@ -280,22 +247,53 @@ eggs =
280247
[sources]
281248
collective.easyform = git https://github.com/collective/collective.easyform.git
282249
```
250+
````
251+
`````
252+
253+
```{tip}
254+
When installing an add-on from source, it's best not to pin a version.
255+
This way you always get the version that's currently available in the source control system.
256+
```
257+
258+
259+
(install-the-add-on-source-label)=
260+
261+
### Install the add-on
262+
263+
Stop the backend with {kbd}`ctrl-c`.
283264

284265
To actually download and install the new add-on, run the following command.
285266

267+
`````{tab-set}
268+
````{tab-item} uv
269+
:sync: uv
270+
286271
```shell
287-
bin/buildout
272+
make backend-build
288273
```
274+
````
275+
276+
````{tab-item} pip
277+
:sync: pip
278+
279+
```shell
280+
make backend-build
281+
```
282+
````
289283
284+
````{tab-item} Buildout
285+
:sync: buildout
286+
287+
```shell
288+
bin/buildout
289+
```
290290
```{seealso}
291291
This approach uses the [`mr.developer`](https://pypi.org/project/mr.developer/) Buildout extension.
292292
```
293-
294293
````
295-
296294
`````
297295

298-
Now restart the backend.
296+
Next, restart the backend.
299297

300298
```{seealso}
301299
{doc}`run-plone`

0 commit comments

Comments
 (0)