Explain how to switch to add native namespace #1981
Conversation
To go along with the PLIP 3928.
gforcada
changed the title
|
@gforcada this is a how-to guide for developers, so it belongs in I'll do a thorough non-technical review after the technical structure and details are reviewed and approved. Thank you! |
| # create a branch for it | ||
| git checkout -b $MAJOR.x | ||
| # push the newly created branch | ||
| git push $MAJOR.x |
There was a problem hiding this comment.
This complains that for example 4.x is not a remote. This seems enough:
| git push $MAJOR.x | |
| git push |
|
|
||
| ```shell | ||
| # list all tags | ||
| git for-each-ref --sort=taggerdate --format '%(tag)' |
There was a problem hiding this comment.
I have not used the for-each-ref command before, thanks for sharing.
When I try it, I get some empty lines as well, for references in refs/heads and refs/remotes. We can restrict to only tags:
| git for-each-ref --sort=taggerdate --format '%(tag)' | |
| git for-each-ref --sort=taggerdate --format '%(tag) refs/tags |
| # list all tags | ||
| git for-each-ref --sort=taggerdate --format '%(tag)' | ||
| # get the last tag's major number | ||
| MAJOR=`git for-each-ref --sort=taggerdate --format '%(tag)' | tail -n1 | cut -d"." -f1` |
There was a problem hiding this comment.
Same here for good measure, only tags:
| MAJOR=`git for-each-ref --sort=taggerdate --format '%(tag)' | tail -n1 | cut -d"." -f1` | |
| MAJOR=`git for-each-ref --sort=taggerdate --format '%(tag)' refs/tags | tail -n1 | cut -d"." -f1` |
| !!! note | ||
| Only relevant for Plone core packages | ||
|
|
||
| Clone the repository or ensure you are at latest changes: |
There was a problem hiding this comment.
I would add a line of explanation:
| Clone the repository or ensure you are at latest changes: | |
| This part is only needed when the `main` or `master` branch is used on multiple versions of the Plone core development buildout. | |
| Clone the repository or ensure you are at latest changes: |
| git push | ||
| ``` | ||
|
|
||
| !!! note |
There was a problem hiding this comment.
| !!! note | |
| Now check if you need to do the same on the 6.0 branch of `buildout.coredev`. | |
| !!! note |
|
|
||
| ```shell | ||
| python -c "import tarfile; print(len(tarfile.open('dist/$package.tar.gz', 'r:gz').getnames()))" | ||
| python -c "from zipfile import ZipFile; print(len(ZipFile('dist/$package.whl').namelist()))" |
There was a problem hiding this comment.
| python -c "from zipfile import ZipFile; print(len(ZipFile('dist/$package.whl').namelist()))" | |
| python -c "import glob; import zipfile; print(len(zipfile.ZipFile(glob.glob('dist/*.whl')[0]).namelist()))" |
| python -c "from zipfile import ZipFile; print(len(ZipFile('dist/$package.whl').namelist()))" | ||
| ``` | ||
|
|
||
| If all numbers match, review the changes once more, push the branch with the changes for others to review it. |
There was a problem hiding this comment.
There will be a few less files in the new distributions.
| If all numbers match, review the changes once more, push the branch with the changes for others to review it. | |
| It is okay if the numbers are slightly lower. | |
| For obvious reasons the old source distribution will have one or more extra `__init__.py` files. | |
| Both old distributions are expected to have an extra `namespace_packages.txt` file and possible an `x-nspkg.pth` file. | |
| If you lose more than a few files though, something is wrong. | |
| If the numbers are close enough, review the changes once more, and push the branch with the changes for others to review it. |
| And update the scaffolding files with `plone.meta`: | ||
|
|
||
| ```shell | ||
| uvx --from plone.meta config-package . |
There was a problem hiding this comment.
In my initial comment in plone/meta#297 I first run config-package passing a specific branch name matching the one used by the pep-420 script, then update the test matrix, run config-package again, and finally run the pep-420 script.
You run the pep-420 script first, which I think makes sense. But then we should tell config-package to use the current branch:
| uvx --from plone.meta config-package . | |
| uvx --from plone.meta config-package --branch current . |
| Get the list of tests, like before and compare the lists to ensure that the same amount of tests are found. | ||
|
|
||
| ```shell | ||
| tox run -e test -- --list-tests |
There was a problem hiding this comment.
I think we can just get the number of lines:
| tox run -e test -- --list-tests | |
| tox run -e test -- --list-tests | wc -l |
| cd $package | ||
| uvx --from plone.meta switch-to-pep420 . | ||
| ``` | ||
|
|
There was a problem hiding this comment.
| Note that this will also bump the version to a new major release. | |
| If the `main` or `master` branch is already an alpha version that is only used in Plone 6.2, you can specify that you don't want this version bump by adding the `--no-breaking` option. | |
I should probably add this logic to the bumpversion command from zest.releaser.
To go along with the plone/Products.CMFPlone#3928
Disclaimer: I have no idea where would be the best place to put this documentation within the structure, and probably the admonitions style is not the right one.
We can polish, but before nitpicking on this details, let's agree on the structure of the document and if it explains all the relevant steps and are clear enough.
Once that's done we can do the polish.
@mauritsvanrees @davisagli: given a random Plone contributor, do you think the steps cover all the steps, and are clear enough? I made it generic enough (with tips to skip sections) so that it can be reused for
collectiveor private packages, where we can not convert all ourselves.📚 Documentation preview 📚: https://plone6--1981.org.readthedocs.build/