Update publish-pypi.md with consistent usage for "test PyPI".

[ptressel]

Refer to "test PyPI" with consistent case and punctuation (with the exception of uppercase T when this appears at the start of a sentence).

[lwasser]

i know @ucodery is there sprinting too and am curious about his thoughts. I think i / wewrote it out this way because of this on the testPyPi website. I really don't know what pypi generally prefers but they do refer to the page as TestPyPI on that page so we might want to stick with that. let me know what you think @ptressel

[ucodery]

I definitely recall trying to normalize all these references 😅 . I don't recall settling on TestPyPI, but I never really checked how the site refers to itself. I recall going with either "test pypi" or "test PyPI" but don't remember which. I'll restate what I said during the sprints: I don't overly care how we do it but I would appreciate a consistent spelling. This is obviously easy to get out-of-sync on. And I wish we could make spellcheck catch it in the future! (Not sure that's possible).

[ptressel]

There is "prior art" for TestPyPI -- it is spelled that way in the Python docs. The actual website is test.pypi.org. Here is the reference: https://packaging.python.org/en/latest/guides/using-testpypi/ In the current revision, there was one instance of "TestPyPI", but many instances of the expression "test PyPI". The former is a name, the latter is a description of its purpose. Since this is documentation, there is no need for "aesthetics", as in an English essay, where one might be advised to not keep using the exact same expression over and over. :D :D :D One option would be to change everything to TestPyPI, but add a parenthetical note on the first use saying that this is provided to test package deployment, and note that the production PyPI should be used for one's fully tested package that is ready to go live. I was going with the most common form in the current version, which is the one we picked at the sprint. Let me know if TestPyPI is preferable.

…

-- Pat

[ptressel]

Hmm...why don't I do a pass to switch to TestPyPI, so we can see what that looks like. Since we have the official doc now, we can peek at how they describe it.

…

-- Pat

[lwasser]

Hmm...why don't I do a pass to switch to TestPyPI, so we can see what that looks like. Since we have the official doc now, we can peek at how they describe it.

@ptressel @ucodery that sounds good to me!! let's use TestPyPI to align with his PyPA spells things!! many thanks!

FUTURE IDEA: This is of course for another issue / PR BUT there is this tool I use locally called Vale that @Batalex turned me on to. it's nice because you can create your own style guide. i wonder if there is a way to set this up as a ci check for the organization in the future? we could then have the style guide information in a single repo and use it across all of our repositories.

[willingc]

And hello @ptressel. Nice to see you sprinting here. It's been too long since I have seen you at a conference. Hope all is well.

[ptressel]

This will have a merge conflict with the previous PR for this file, which removed a near-duplicate line. When I branched this file, that PR was not yet merged, but it is now. I forgot that the other change was a separate PR, so re-deleted that duplicate line. Unless...maybe GitHub's version of git can detect that the later change is identical, and deal with it. The automated check says "Merging is blocked", but does not give the reason as a merge conflict, rather, "merging can be performed automatically" with review.

This branch also has two previous commits that are essentially replaced by the latest one. So if "squash and merge" is allowed, it would be cleaner to squash all the commits. The latest commit message has all the information, so if the GitHub squash process is anything like the command line rebase, the earlier commit messages could be edited out.

[ptressel]

Hello right back, @willingc ! I'm retired now, and have been just a titch embarrassed that I'm not working on some open-source project. (The one I was working on switched to doing simulation rather than hands-on work during the pandemic, and the simulation tool needs a GPU...which I don't have.)

[ucodery]

Why is the above docs section being added to the TODO? This will prevent the content from rendering. Might be a mistake.

[ptressel]

Look at the current rendered page. The code block about hatch is spurious -- it does not belong in the visible text there. It just appears out of nowhere, prior to the start of the meaningful text in the page. Rather, it is part of the "todo" section, and is referred to by the "todo."

Also, if you look at the current raw text, you will see that the triple-colon markup did not match opening and closing triple-colon marks. There was one extra, in the middle of the "todo" section, and one missing, where the end of the first "admonition" should have been (going by how that is structured in other pages, where the leading "workflow" image is not inside the "admonition").

I am guessing that @ucodery is looking at the "Preview", and seeing the visible triple-colon marks...? Look at other unmodified pages using "Preview", and they will be visible there as well.

This brings up a more general issue. When we work on pages on GitHub, and view the "Preview", that apparently does not run whatever markdown extensions are in use. In particular, the rendering on GitHub Preview does not know about the triple-colon markup, so just treats it as plain text.

So...maybe we should be looking into a way to do the full rendering as part of testing. That might mean doing things the Old Way, with folks doing command-line git on their local machines, and doing the rendering there, so as to see what the finished product will look like. That is significantly higher friction, but if it resolves questions like this, maybe it's the right thing to do.

[ptressel]

Note the "todo" may be obsolete -- some of those may be "done". ;-). The relevant line in the "todo" is:

"if we go with hatch then we may want to add this to the installable code lesson"

followed by the hatch code block to add to the "installable code lesson". That's already in, right at the top of the "Install hatch" section in the hatch page, so it looks like at least part of that "todo" is "done".

Aaaand, this brings up another issue: Should responses to commands be shown? And if so, how should they be formatted? The "pipx install hatch" command in this page includes the response, where the one over in the hatch page does not. Which is less confusing? Is it useful for folks to know what a correct response looks like, as opposed to an error message? There are other examples of commands, both with and without visible responses, and the formatting of the response is not consistent. Some have "#" before the response, others don't.

[ucodery]

Yes, you are right, I wasn't looking at the html rendered docs. I got confused matching up ::: myself, but this renders great, thanks for cleaning this up. However, I don't think we need to keep CLI examples around in TODOs. The install steps as well as the 3rd bullet can be dropped entirely from the TODO as they are already addressed elsewhere.

As for github's less-than rendering, I'm not sure there is anything we can do. this guide is using MyST which is essentially a mark up transpiler. It reads fully valid markdown files, which are tagged as such in the file name, so github is doing the best it can.

As for command line output - this is a very tricky question. I can see now that we do it all sorts of ways. I'm not aware of any documentation out there that gets it "right" all of the time. Partly because ```bash might be capturing a pure bash script, or it might be copy from the terminal, which is mixing stdin, stdout, stderr. I sometimes have the same issue with Python, where I want to show the repr output as in the interactive shell. Personally I try to mark the command section of interactive code examples with >>> in Python and $ in Bash, but even still I am inconsistent, even with my use of comments.

[ptressel]

I was meaning to inquire... There are a lot of hatch commands here, that maybe could go in the hatch tutorial, if it would be useful to have that be a somewhat standalone guide to hatch, rather than setup / installation of hatch for later use in other tutorials. Even if these do go in the hatch tutorial, it could still be useful to repeat them here, with the specific arguments that apply to publishing to TestPyPI. I gather that the separate hatch tutorial was more recent than the use of hatch in the other tutorials.

[ptressel]

Ok, 1st and 3rd todos are removed. A note about converting setup.py is already in the Hatch tutorial.

About command line stuff... I was hesitating to bring this up, but... There are a fair number of folks using Windows. The commands may look a bit different if executed in cmd...but not always. A fair number of tools that come in from the *x world will use forward slashes in paths, or not understand a drive letter, or require their own special syntax for that. Others will take back slashes, but need them quoted. The best ones know what OS they're running on, and do "when in Rome...".

Windows users could install Git Bash. Or Windows Subsystem for Linux (WSL; which allows having an entire Linux distro under Windows). Or the classic Cygwin. Or adapt the commands for running directly on Windows. The easiest option is likely Git Bash. It's not entirely friction-free, however, as Git Bash's executable path may differ from the Windows path.

I've mostly ended up modifying commands so they work on cmd, except when the documentation strongly encourages use of Git Bash. Or when there's a canned development environment that can be run on a virtual machine. That's what we used to do for an open-source emergency management tool I used to work on, when we participated in hackathons. It could take the entire day to set up our environment, so instead, we prepared pre-configured virtual machine images.

The following has a good list of the options, one could just drop in a reference to this at the outset, wherever it says "we don't support Windows". :D :D :D

https://itsfoss.com/run-linux-commands-in-windows/

[ucodery]

Thanks for raising this @ptressel. We do think about OS inter-operability deeply sometimes. Unfortunately we don't pay attention to it nearly often enough, and probably even less do we test what we recommend on Windows.

#106 (comment)
#106 (comment)
#120 (comment)

This is a really big topic thought, so I have opened a new issue #240 so we don't derail your contribution.

[lwasser]

hi all 👋 it doesn't surprise me that there are some todo's left (likely by me) in the text. And also because i don't have windows, i don't catch windows-specific issues BUT we can add tabs for commands that might look different in a windows shell if needed. i think @ucodery opening #240 is perfect. my hope is that over time as more people test these out we can refine and make sure more use cases are covered.

[ucodery]

maybe just drop the reference to warehouse. It's an entirely PyPI name and not generic or recognizable as a term with other package repositories.

[ptressel]

I agree that it could be dropped. I'll take it out. But here's why I left it in:

I was assuming that there was an attempt to avoid jargon, under the assumption that folks won't be familiar with "repository", and "warehouse" was chosen as the surrogate for repository. There is talk elsewhere of having a glossary -- adding definitions would help familiarize readers with the terms, as they will surely encounter them in other documentation. Even if "repository" isn't universal, it is much more common than "warehouse", for software. Were this data, then "repository" would still likely win. For data, terms like "warehouse" do appear, but they tend to be in product names or advertising materials, or have been assigned new, specific meanings.

([gripe]As often happens, folks are taking normal (usually English) words, and attaching special meaning to them...like the word "lake", as in "data lake". Then they sniff when others don't know that they have applied their own special meaning for the actual in-normal-use word. Harumph. Mathematicians are the prime culprits here, especially algebraicists -- "group", "ring", "field"... At least when physicists grab normal words and repurpose them, they are making jokes, because physics has gone wild, and the physicists are well aware, hence quark properties like "strangeness" and "charm", and quantum chromodynamics, and "bra" and "ket" vectors,... I know what a "warehouse" is...it has physical stuff in it, on shelves and pallets.[/gripe])

There are some other guidelines for documentation vs. specialized terms, in addition to having a glossary, that we might use: First is the convention to define terms on first use. I was trying to move such definitions up to the first use within the page. Second is to have a "conventions" section at the beginning of the document, that lists formatting and what it means, e.g. "Literal commands, to be entered at the command line, are shown in fixed-pitch fonts." and "Command options that the user should replace with their own values are shown surrounded by angle brackets. Replace the angle brackets and the descriptive text in them with the appropriate value for your package."

I've got a list of other terms that might be appropriate for a glossary.

[ucodery]

For data, terms like "warehouse" do appear, but they tend to be in product names or advertising materials

This is exactly what has happened here. "warehouse" is the name of the software that powers pypi.org. Specifically it is the Python package (also self-published on pypi.org) that the pypi.org administrators work on for exactly this one site.

[lwasser]

oh yikes 🤯 also repository can be confusing as my brain goes to "github repository" vs pypi repository which is a different type of "repository". i think the glossary will be great and maybe a nice activity for another sprint - pycon maybe or scipy?!

[ucodery]

Suggested change

1. **[TestPyPI](https://test.pypi.org):** TestPyPI is a package repository provided by PyPI that you can use for testing that your package can be uploaded correctly, and that you can use to test that your package downloads and installs correctly. This is a great place to practice and learn how to publish a package without exposing your incomplete or not fully tested package on the real PyPI service.

1. **[TestPyPI](https://test.pypi.org):** TestPyPI is a package repository provided by PyPI that you can use for testing that your package can be uploaded, downloaded, and installed correctly. This is a great place to practice and learn how to publish a package without exposing your incomplete package on the real PyPI service.

[ptressel]

Done -- thanks!

[ucodery]

Suggested change

	The steps for publishing on TestPyPI vs. real PyPI are the similar with the
	The steps for publishing on TestPyPI vs. PyPI are similar with the

[ptressel]

Done -- thanks!

[ucodery]

Suggested change

	your account on test PyPI so you can publish your package.
	your account on TestPyPI so you can publish your package.

[ptressel]

Done -- thanks!

[ucodery]

Suggested change

	- Add the word `__token__` for your username. This tells test PyPI that you are using a token value rather than a username.
	- Add the word `__token__` for your username. This tells TestPyPI that you are using a token value rather than a username.

[ptressel]

Done -- thanks! (At one point, I lost all my edits. Not sure quite what happened, but I may have accidentally used the browser's "back" button.)

[ucodery]

In fact, you cannot, because TestPyPI deletes accounts after a time.

Do you have a citation for this? I've never heard this and I have a TestPyPI account which I have let go fallow for a few years before but which I still have access to.

[ptressel]

It's a warning in the Python packaging guide at python.org. I'll change it to conditional, "may delete".

https://packaging.python.org/en/latest/guides/using-testpypi/

"The database for TestPyPI may be periodically pruned, so it is not unusual for user accounts to be deleted."

I'm guessing it is there because the PyPI maintainers want to reserve the right to clear out old stuff periodically, and to make sure TestPyPI is not being used to serve packages to users, and just as a security measure, in case packages with malware might creep in. It may be that they rarely do this, but they want to be able to point to a warning, if they do do it, and folks complain.

[ucodery]

Suggested change

	- Setup an account on TestPyPI (the process is similar for the real PyPI)
	- Setup an account on TestPyPI (the process is similar for PyPI)

[ucodery]

Looks Great ✅

[ptressel]

Thanks, @ucodery ! (Just yesterday, I was at a meeting of the "rules & bylaws" committee of an organization I belong to. One thing that came up was whether our "policy" committee should be permitted to offer wordsmithing help to folks wanting to propose resolutions. We used to have a resolutions committee that did that, but that faded away, on grounds that anyone can bring any resolution, and we should not alter their wording. I said, this was only done in collaboration with the resolution proposer, and they had control over the result. Someone else then said, anyone can benefit from good editing and proofreading. I followed that by saying, right now, as we speak, I am benefitting from excellent editorial advice on a technical document. ;-) )

[lwasser]

and now i see why @willingc has been working on me to avoid leaving too many in line comments / todos and instead opening issues!! 😆 let's get this pr merged as well. thank you again for all of the thoughtful conversation and review here @ucodery @ptressel @willingc i really enjoyed looking at all of the discussion.