diff --git a/docs/admin/reference/settings.md b/docs/admin/reference/settings.md index 9f94f592cf..96d5d7c71d 100644 --- a/docs/admin/reference/settings.md +++ b/docs/admin/reference/settings.md @@ -393,8 +393,8 @@ The default setting is `False`. When set to `True`, each task records various di and stores them as separate artifacts. To download the data, issue GET requests to `${TASK_HREF}profile_artifacts/`. The artifacts are cleaned up automatically by the orphan cleanup. -> - memory.datum - the task's max resident set size in MB -> - pyinstrument.html - the output of the pyinstrument profiler, if installed +- memory.datum - the task's max resident set size in MB +- pyinstrument.html - the output of the pyinstrument profiler, if installed diff --git a/docs/dev/guides/plugin-walkthrough.md b/docs/dev/guides/plugin-walkthrough.md index 587262beaf..0a84eeeb66 100644 --- a/docs/dev/guides/plugin-walkthrough.md +++ b/docs/dev/guides/plugin-walkthrough.md @@ -86,18 +86,12 @@ See `writing-tasks`. Almost all plugins must implement a `sync` task, most imple ## Plugin Completeness Checklist -> - `Plugin django app is defined using PulpAppConfig as a parent ` -> -> - `Plugin entry point is defined ` -> -> - [pulpcore is specified as a requirement](https://github.com/pulp/pulp_rpm/blob/main/requirements.txt#L6) -> -> - Necessary models/serializers/viewsets are `defined ` and `discoverable `. At a minimum: -> -> - models for plugin content type, remote, publisher -> - serializers for plugin content type, remote, publisher -> - viewset for plugin content type, remote, publisher -> -> - `Errors are handled according to Pulp conventions ` -> -> - Docs for plugin are available (any location and format preferred and provided by plugin writer) +- `Plugin django app is defined using PulpAppConfig as a parent ` +- `Plugin entry point is defined ` +- [pulpcore is specified as a requirement](https://github.com/pulp/pulp_rpm/blob/main/requirements.txt#L6) +- Necessary models/serializers/viewsets are `defined ` and `discoverable `. At a minimum: + - models for plugin content type, remote, publisher + - serializers for plugin content type, remote, publisher + - viewset for plugin content type, remote, publisher +- `Errors are handled according to Pulp conventions ` +- Docs for plugin are available (any location and format preferred and provided by plugin writer) diff --git a/docs/dev/guides/release_process.md b/docs/dev/guides/release_process.md index d8bffb820d..4bbeeb8cc9 100644 --- a/docs/dev/guides/release_process.md +++ b/docs/dev/guides/release_process.md @@ -1,47 +1,25 @@ - - # Pulpcore Release Process -Here are the steps to take to release a Pulpcore version. New Y-releases of Pulpcore must take all of them. -**A new Z-release need only execute steps 2, 3, and 4.** - -> - **"I am releasing a new Y-branch of Pulpcore (e.g., 3.23)"**: -> -> 1. Via the Github Actions, trigger a ["Create new release branch"](https://github.com/pulp/pulpcore/actions/workflows/create-branch.yml) job. -> -> - **"I am releasing a new Z-release of Pulpcore (e.g., 3.23.0, 3.22.12)"**: -> -> 2. Via the Github Actions, trigger a ["Release pipeline"](https://github.com/pulp/pulpcore/actions/workflows/release.yml) job by specifying the release branch (X.Y) and the tag (X.Y.Z) of the release. -> 3. Once the release is available, make an announcement on Pulp discourse, in the "Announcements" category. See [example](https://discourse.pulpproject.org/t/pulpcore-3-21-0-is-now-available/626). -> 4. The CI automation will create PRs with the Changelog update and Versions bump that will need to be merged. -> -> - **"I have released a new Y-release of Pulpcore, followup actions"**: -> -> 5. Arrange for a new oci-image for that release by following the ["oci-images Release Instructions"](https://github.com/pulp/pulp-oci-images/blob/latest/docs/developer-instructions.md). -> 6. Update the `ci_branches` stanza in [pulpcore's template.config.yml](https://github.com/pulp/pulpcore/blob/main/template_config.yml#L22). This stanza should always (and only) contain: -> -> > - The most-current (i.e., newly-released) branch. -> > - All branches in use by supported downstream products (see below). These are branches we will consider backporting selected bugfixes to. -> -> 7. Monitor [pulpcore pull-requests](https://github.com/pulp/pulpcore/pulls) for creation of a PR such as ["Update supported versions"](https://github.com/pulp/pulp-ci/pull/826). Such PRs are created by [this job](https://github.com/pulp/pulp-ci/actions/workflows/supported.yml). The job may have been disabled if there hasn't been any release-activity in the repository for at least 60 days. You will need to re-enable it in this case. - -Some possible failures of **Step 2**, above, include: - -> - If release-tag is new but not based on current-dev, workflow will complain and fail -> - If release-tag is for an existing release (by accident) , the workflow won't fail until the docs-pub. Cleaning this up can be Exciting. - -# Active branches as of 2023-05-16: +Here are the steps to take to release a Pulpcore version: + +- A new Y-releases must take all steps. +- A new Z-release need only execute steps 2, 3, and 4. + +## Process + +- **"I am releasing a new Y-branch of Pulpcore (e.g., 3.23)"**: + - 1) Via the Github Actions, trigger a ["Create new release branch"](https://github.com/pulp/pulpcore/actions/workflows/create-branch.yml) job. +- **"I am releasing a new Z-release of Pulpcore (e.g., 3.23.0, 3.22.12)"**: + - 2) Via the Github Actions, trigger a ["Release pipeline"](https://github.com/pulp/pulpcore/actions/workflows/release.yml) job by specifying the release branch (X.Y) and the tag (X.Y.Z) of the release. + - 3) Once the release is available, make an announcement on Pulp discourse, in the "Announcements" category. See [example](https://discourse.pulpproject.org/t/pulpcore-3-21-0-is-now-available/626). + - 4) The CI automation will create PRs with the Changelog update and Versions bump that will need to be merged. +- **"I have released a new Y-release of Pulpcore, followup actions"**: + - 5) Arrange for a new oci-image for that release by following the ["oci-images Release Instructions"](https://github.com/pulp/pulp-oci-images/blob/latest/docs/developer-instructions.md). + - 6) Update the `ci_branches` stanza in [pulpcore's template.config.yml](https://github.com/pulp/pulpcore/blob/main/template_config.yml#L22). This stanza should always (and only) contain: + - The most-current (i.e., newly-released) branch. + - All branches in use by supported downstream products (see below). These are branches we will consider backporting selected bugfixes to. + - 7) Monitor [pulpcore pull-requests](https://github.com/pulp/pulpcore/pulls) for creation of a PR such as ["Update supported versions"](https://github.com/pulp/pulp-ci/pull/826). Such PRs are created by [this job](https://github.com/pulp/pulp-ci/actions/workflows/supported.yml). The job may have been disabled if there hasn't been any release-activity in the repository for at least 60 days. You will need to re-enable it in this case. + me possible failures of **Step 2**, above, include: + - If release-tag is new but not based on current-dev, workflow will complain and fail + - If release-tag is for an existing release (by accident) , the workflow won't fail until the docs-pub. Cleaning this up can be Exciting. -> - pulpcore -> -> - 3.23 (galaxyNG/4.7) -> - 3.22 (katello/4.9) -> - 3.21 (katello/4.7, galaxyNG/4.6, RHUI/4.3) -> - 3.18 (katello/4.5) -> - 3.16 (katello/4.3) -> -> - pulp_file -> -> - 1.12 (katello/4.9) -> - 1.11 (katello/4.7) -> - 1.10 (katello/4.3. 4.5) diff --git a/docs/dev/guides/test-pulp.md b/docs/dev/guides/test-pulp.md index 864b2c1524..857e4856ca 100644 --- a/docs/dev/guides/test-pulp.md +++ b/docs/dev/guides/test-pulp.md @@ -31,8 +31,8 @@ Only the tests for features related to `pulpcore` should live in this repository Functional tests for features related to a specific plugin should live in the plugin repository itself. For example: -> - [File Plugin](https://github.com/pulp/pulpcore/tree/master/pulp_file/tests/functional) -> - [RPM Plugin](https://github.com/pulp/pulp_rpm/tree/master/pulp_rpm/tests/functional) +- [File Plugin](https://github.com/pulp/pulpcore/tree/master/pulp_file/tests/functional) +- [RPM Plugin](https://github.com/pulp/pulp_rpm/tree/master/pulp_rpm/tests/functional) ## Prerequisites for running tests diff --git a/docs/dev/learn/other/metadata-signing.md b/docs/dev/learn/other/metadata-signing.md index f3b5c8dbe0..d406c636bf 100644 --- a/docs/dev/learn/other/metadata-signing.md +++ b/docs/dev/learn/other/metadata-signing.md @@ -53,61 +53,68 @@ instantiation. For more information see the corresponding `workflow documentation `. +## Procedure Sample -The following procedure may be taken into account for the plugin writers: - -> 1. Let us assume that a file repository contains the field `metadata_signing_service`: -> -> ```python -> metadata_signing_service = models.ForeignKey( -> AsciiArmoredDetachedSigningService, -> on_delete=models.SET_NULL, -> null=True -> ) -> ``` -> -> In the serializer, there is also added a corresponding field that serializes `metadata_signing_service`, -> like so: -> -> ```python -> metadata_signing_service = serializers.HyperlinkedRelatedField( -> help_text="A reference to an associated signing service.", -> view_name="signing-services-detail", -> queryset=models.AsciiArmoredDetachedSigningService.objects.all(), -> many=False, -> required=False, -> allow_null=True -> ) -> ``` -> -> 2. Retrieve a desired signing script via the field `metadata_signing_service` stored in the repository: -> -> ```python -> metadata_signing_service = FileRepository.objects.get(name='foo').metadata_signing_service -> ``` -> -> A plugin writer can create a new repository with an associated signing service in the following two ways: -> -> > - Using Python: -> > -> > ```python -> > signing_service = AsciiArmoredDetachedSigningService.objects.get(name='sign-metadata') -> > FileRepository.objects.create(name='foo', metadata_signing_service=signing_service) -> > ``` -> > -> > - Using HTTP calls: -> > -> > ```bash -> > http POST :24817/pulp/api/v3/repositories/file/file/ name=foo metadata_signing_service=http://localhost:24817/pulp/api/v3/signing-services/5506c8ac-8eae-4f34-bb5a-3bc08f82b088/ -> > ``` -> -> 3. Sign a file by calling the method `sign()`: -> -> ```python -> with tempfile.TemporaryDirectory("."): -> try: -> signature = metadata_signing_service.sign(metadata.filepath) -> except RuntimeError: -> raise -> add_to_repository(metadata, signature) -> ``` +The following procedure may be taken into account for the plugin writers. + +### Context + +Let us assume that a file repository contains the field `metadata_signing_service`: + +```python +metadata_signing_service = models.ForeignKey( + AsciiArmoredDetachedSigningService, + on_delete=models.SET_NULL, + null=True +) +``` + +In the serializer, there is also added a corresponding field that serializes `metadata_signing_service`, +like so: + +```python +metadata_signing_service = serializers.HyperlinkedRelatedField( + help_text="A reference to an associated signing service.", + view_name="signing-services-detail", + queryset=models.AsciiArmoredDetachedSigningService.objects.all(), + many=False, + required=False, + allow_null=True +) +``` + +### Associate a signing service + +Retrieve a desired signing script via the field `metadata_signing_service` stored in the repository: + +```python +metadata_signing_service = FileRepository.objects.get(name='foo').metadata_signing_service +``` + +A plugin writer can create a new repository with an associated signing service in the following two ways: + +=== "Using Python" + + ```python + signing_service = AsciiArmoredDetachedSigningService.objects.get(name='sign-metadata') + FileRepository.objects.create(name='foo', metadata_signing_service=signing_service) + ``` + +=== "Using HTTP calls" + + ```bash + http POST :24817/pulp/api/v3/repositories/file/file/ name=foo metadata_signing_service=http://localhost:24817/pulp/api/v3/signing-services/5506c8ac-8eae-4f34-bb5a-3bc08f82b088/ + ``` + +### Sign the file + +Sign a file by calling the method `sign()`: + +```python +with tempfile.TemporaryDirectory("."): + try: + signature = metadata_signing_service.sign(metadata.filepath) + except RuntimeError: + raise + add_to_repository(metadata, signature) +``` diff --git a/docs/dev/learn/sync_pipeline/sync_pipeline.md b/docs/dev/learn/sync_pipeline/sync_pipeline.md index e5a2ed0603..3b5b30d9ee 100644 --- a/docs/dev/learn/sync_pipeline/sync_pipeline.md +++ b/docs/dev/learn/sync_pipeline/sync_pipeline.md @@ -30,14 +30,14 @@ this is the part of the pipeline specific to the repository type. The pulp plugin api provides the following stages which also comprise the default pipeline in the following order: -> 1. `pulpcore.plugin.stages.QueryExistingContents` -> 2. `pulpcore.plugin.stages.QueryExistingArtifacts` -> 3. `pulpcore.plugin.stages.ArtifactDownloader` -> 4. `pulpcore.plugin.stages.ArtifactSaver` -> 5. `pulpcore.plugin.stages.ContentSaver` -> 6. `pulpcore.plugin.stages.RemoteArtifactSaver` -> 7. `pulpcore.plugin.stages.ResolveContentFutures` -> 8. `pulpcore.plugin.stages.ContentAssociation` +1. `pulpcore.plugin.stages.QueryExistingContents` +2. `pulpcore.plugin.stages.QueryExistingArtifacts` +3. `pulpcore.plugin.stages.ArtifactDownloader` +4. `pulpcore.plugin.stages.ArtifactSaver` +5. `pulpcore.plugin.stages.ContentSaver` +6. `pulpcore.plugin.stages.RemoteArtifactSaver` +7. `pulpcore.plugin.stages.ResolveContentFutures` +8. `pulpcore.plugin.stages.ContentAssociation` If the `mirror=True` optional parameter is passed to `DeclarativeVersion` the pipeline also runs `pulpcore.plugin.stages.ContentUnassociation` at the end.