search

python / psf-infra-meta

Meta-repository for PSF backed or managed systems. Created mainly for the issue tracker :)
10 stars 9 forks source link

Consistent announcement strategy for PyPI changes #1

Open ncoghlan opened 7 years ago

ncoghlan commented 7 years ago

Our current approach to significant announcements for PyPI is fairly ad hoc, and varies from case to case.

The lowest common denominator is to send a post to distutils-sig about it, and then @dstufft may tweet about it. Neither of these are great as pure announcement channels (since a lot of other things get posted there as well).

Examples:

Inline updates in the PyPI web UI itself are possible, but aren't straightforward for the legacy service, and don't necessarily reach folks relying solely on automated access.

Bigger updates that also require changes to other tools have gone through the full PEP process when there were design details to be resolved:

However, that's less appropriate for things that aren't design discussions, and are instead just changes to operational details that nevertheless require advance notice to let people update configuration settings to avoid future problems (like service migrations to a different domain)

A dedicated topic on the PSF blog seems like a good vehicle, but we don't currently have a standard way of requesting posts there, nor a standard place to collaborate on the wording of things.

Examples of PyPI related blog announcements:

offbyone commented 7 years ago

Something to consider is that, while core devs et al are regular readers of these venues, or subscribed to mailing lists, I suspect the number of people who read them is dwarfed by the number of unique users who use tools like pip, even interactively. Per my twitter suggestion, integrating some kind of notification mechanism into pypi/pip -- one, ideally, that can be consumed by other services as well (Travis &c) -- would cover users who don't engage with the community but still use the tools.

ericholscher commented 7 years ago

+1 on putting a banner on pypi, and having that push to a blog, which gets pushed out on update (via RSS, Twitter, & Mailing List). Having something in pip itself would be really neat, but likely require a decent bit of architecture, and also need to be more thought out.

kushaldas commented 7 years ago

I would like to start writing blog posts on these points. They will not be big, but small and to the point related to the infrastructure improvements. I can work with the rest of psf-blog team if required.

ncoghlan commented 7 years ago

If the PyPI announcement banner is structured as a JSON endpoint that the front-end queries (rather than injecting the message on the server), that should leave the door open to automating announcements in other contexts as well.

offbyone commented 7 years ago

I agree; that's the model I'd expect to see. We actually do something similar as a notification method in-house, and it works pretty well. The userbase is a bit smaller than the pip user base, but not by as much as you'd think, and it scales pretty well too.

Honestly, TTY detection on Windows would probably be the hard part :)

ncoghlan commented 7 years ago

OK, so here's an initial proposal:

Process changes:

(While we could add a pypi-announce mailing list as well, I don't see a lot of value in adding that over the RSS/Atom feed from Blogger. If we did add it, we may want to use the experimental Mailman 3 server that I believe is already kicking around somewhere, rather than the default Mailman 2 server)

Technical changes:

Scope clarifications based on subsequent discussion:

offbyone commented 7 years ago

That seems to cover enough of the bases for a solid start.

gvanrossum commented 7 years ago

I feel so out of touch. I never knew about most of the things Nick mentioned.

I wonder if there aren't two different audiences that need different channels: developers who upload things, and people who download stuff. The latter presumably have less need to read about site changes, as long as pip still works (if the search box on the site changes they'll presumably figure it out). But uploaders might depend on things that change and need to be told about the new hotness for uploading (e.g. it took me a while to learn about twine).

offbyone commented 7 years ago

That's why I think the interactive channel will pay off; you only have to modify the uploading tools -- most of which are somewhat interactive, or at least amenable to human oversight -- to get a lot of coverage for notices about site changes or issues.

ncoghlan commented 7 years ago

I agree it's mainly the upload case where problems can arise - in addition to the two PEPs I already listed, a number of our other interoperability PEPs have also involved introducing new restrictions on uploads (e.g. requiring PEP 440 compliant version identifiers) where even though we took steps to minimise the negative impact, we're still potentially affecting the publication workflows of dozens or hundreds of people.

By contrast, for pure consumers, we're in a better position to preserve backwards compatibility (since we can ensure the client tools remain tolerant of legacy publication formats), and we also have a greater need to do so (as not only do we have a couple of orders of magnitude more consumers than we do publishers, publishers also tend to be better positioned to upgrade their tools and related configuration settings than the typical PyPI consumer)

So I think it would even be reasonable to scope the initial set of technical changes specifically to publisher announcements, and only have twine consume it on the CLI side of things. If we decide we need a general inline announcement channel later we can add one, but bothering regular PyPI users about publisher-only changes would probably be an anti-feature at this point.

dstufft commented 7 years ago

All of this sounds pretty good, and it shouldn't be very hard to add that into Warehouse even. At one point I even though about some sort of changelog like thing for PyPI (similiar to https://devcenter.heroku.com/changelog) so maybe something like that could be done, with the ability to flag something as an interactive notice for pip or twine but also provide a sort of feed of all the misc changes that maybe aren't important enough for a full push out to everyone notice?

Just an aside, it's pretty cool that I randomly whine on twitter about communication channels and a bunch of people leap into action to figure it out for me ;)

ncoghlan commented 7 years ago

Making another note based on https://github.com/pypa/packaging-problems/issues/98: since PyPI collects email addresses, we do have the option of emailing publishers directly.

While that has generated complaints from mail recipients in the past, that concern could potentially be mitigated by offering a "Notify me about potentially disruptive upcoming service changes" setting in user's profiles.

rsyring commented 7 years ago

While that has generated complaints from mail recipients in the past, that concern could potentially be mitigated by offering a "Notify me about potentially disruptive upcoming service changes" setting in user's profiles.

And making it VERY EASY to opt-out of the emails. If you give a link in the emails that let's someone immediately unsubscribe, as opposed to having to login to a website, find password, find user profile, change preference (etc.), it seems like those who complain about the annoying emails can be pointed to the unsubscribe link and then politely ignored?

ncoghlan commented 6 years ago

In the "yet-another-announcement-channel" category, we've also started using https://packaging.python.org to hold a "What might I have missed?" guide at least for the PyPI service migration: https://packaging.python.org/guides/migrating-to-pypi-org/

brainwane commented 6 years ago

I'm deeply interested in us developing a robust set of announcement channels/methods for PyPI changes -- I'm working on the new Warehouse deployment project, and I'll want to be able to notify the Python community before we redirect pypi.python.org to pypi.org and at a few other points along the way.

So here is my roundup of the things I heard people bring up in this issue, plus some ideas of my own:

[I think a packaging-related announce list would fit well with my mental model of how one publicizes and learns about breaking changes in open source projects -- an organization can make sure that a role account is subscribed to that mailing list and be sure that they'll be informed of breaking changes. But I am open to being wrong here. :)]

I'd love for some of the automated functionality in the above list to be ready within the next couple months -- as we kick off the [pypa/warehouse] deploy planning in earnest in the next few weeks, I'll have a more concrete timeline to share and can break this into separate sub-issues.

ncoghlan commented 6 years ago

A few specific items I would suggest:

And a couple of items I think we need to consider carefully:

dstufft commented 6 years ago

a dedicated "pypi-announce@python.org" mailing list (this is a +1 to @brainwane's suggestion, with a specific name proposal added)

I think packaging-announce or something is better, while primarily used for PyPI I can see cases where we might want to raise wider awareness on non PyPI things.

ncoghlan commented 6 years ago

I'd be OK with packaging-announce, but my rationale for pypi-announce specifically is that service changes are the ones that are truly unavoidable - folks publishing through PyPI or querying PyPI for packages or metadata can't decide to pin themselves to an older version.

By contrast, changes to client side tooling (whether for publishers or consumers) are always going to be a more opt-in affair - even if pip 10 were to include a breaking CLI change (for example), folks could keep using pip 9 until they were ready to deal with the change.

The only time that isn't the case is when folks need to upgrade their client tools (or change their configuration settings) in order to cope with a breaking PyPI change. At that point we're back to pypi-announce being an appropriate name again.

That said, the documentation domain is packaging.python.org, which is why I'd also be fine with packaging-announce (I'm just +0 on that, vs +1 for pypi-announce)

dstufft commented 6 years ago

At the end of the day naming is just painting the bikeshed so it doesn't really matter, I just thought packaging-announce might give us more room to use it for other things (not that the name really stops us!) if needed instead of ending up in a distutils-sig situation.

ncoghlan commented 6 years ago

I think in this case, it's probably better to optimise for "I want announcements about PyPI -> I should follow pypi-announce".

Then the filter we'd apply to announcements in that channel would be "Is the announcement especially relevant to users of PyPI?".

For a new CPython release for example, what we'd announce is things like the Trove classifier being added, rather than necessarily announcing the release itself.

ncoghlan commented 6 years ago

Thanks to @jonparrott, we have a news page in PyPUG now, back filled with notable PyPUG updates for the past several months: https://github.com/pypa/python-packaging-user-guide/pull/404

So what we'd be looking for from this issue is guidance on what other items we considered worth noting in that list (e.g. I think releases for tools mentioned on https://packaging.python.org/guides/tool-recommendations/ would make sense, but probably not releases for tools mentioned in other parts of the guide)

njsmith commented 6 years ago

As an example of a potential not-strictly-pypi-related announcement, I could imagine that after PEP 517 is deployed it'd make sense to put together a nice end-user oriented post about what this means (we now support non-distutils-based build systems!), limitations (watch out for old pips), where to go next (here are some alternative build systems, tips if you want to make your own). Obviously we don't want to spam people, but we do want to make it painless for interested package developers to keep up with this kind of news.

brainwane commented 6 years ago

As the project manager for the Warehouse rollout, I'm going to go ahead and request a pypi-announce@python mailing list from infrastructure-staff@python now, and we can continue on the other requested items in this issue in parallel.

MarkMangoba commented 6 years ago

@brainwane I have created pypi-announce@python.org and packaging-wg members are admins. https://mail.python.org/mm3/mailman3/lists/pypi-announce.python.org/.

brainwane commented 6 years ago

I see we now have a "PyPI" label on the PSF blog; thank you!

I'd love for us to move forward on an automatically generated history of past announcements in Warehouse; for right now I'm ok with adding a link in the FAQ to the PyPI-labelled blog posts, and have filed pypa/warehouse#3139.

Could we also talk about the other suggestions Nick mentioned in https://github.com/python/psf-infra-meta/issues/1#issuecomment-310560260 ? And we could bat them around a bit during the sprint in May.

brainwane commented 6 years ago

Per conversation with @pfmoore just now in IRC:

The pypi-announce list is for major PyPI announcements. I made a promise in the listinfo for pypi-announce that it would just be for PyPI news (like the Warehouse beta -- and once we implement PEP 541, I think it would make sense to do an all-in-one announcement about PEPs 541 and 566), and I want to generally keep that promise to subscribers.

There should be a separate low-traffic announcement list or channel for other really major changes, like pip 10.0. The 10.0 of pip is a big enough deal that I'm fine with advertising its beta and release (2 posts total) on pypi-announce, till we get something else up and running, but I think now that release velocity is going up for packaging tools, let's set up a packaging-announce list.

(Also, http://libraries.io/ has a useful email notification service for new releases; I got the automated "new pip" email from them just fine today.)

@MarkMangoba can you set up a packaging-announce Mailman 3 list please?

njsmith commented 6 years ago

Having two different lists to announce major packaging ecosystem changes seems like maybe one too many? I wouldn't use the list to announce very pip release, but in this case the beginning of PEP 518 support, change in -U, and the pip._internals changes all seem worth a bigger announcement.

brainwane commented 6 years ago

Maybe major non-PyPI packaging ecosystem changes should go to python-announce-list for the next month or so, and then at the sprints in May we can talk about the likely cadence of packaging changes for the next ~year and decide what adjustment to make (changing pypi-announce to packaging-announce, setting up some new list, what have you).

remram44 commented 6 years ago

I think you should consider sending at least the major announcements to the general python-announce list. Some of us were not aware of the need to subscribe to the dist and packaging mailing-lists specifically to be kept posted about major changes.

njsmith commented 6 years ago

Now that the new site's live, maybe we should advertise the new announce list, e.g. on a banner, when everyone's looking at the new pretty and the outage is fresh in their minds?

Right now I literally can't seem to find the list in google (searching for "pypi-announce" doesn't find it), and the only reference to it on pypi.org seems to be buried at the end of this page: https://pypi.org/help/#upcoming-changes