## Goals The goals of the https://github.com/ossf/tac/issues/424 include: * Helping users to understand attestations, including what they are, how they work and what their limitations are * Helping users to understand attestations within the context of other security features * (slightly out of scope - bonus objective) Directing maintainers towards workflows that generate attestations (i.e. by using Trusted Publishing) For new security documentation to be successful, it should be contained within an overall structure that allows users to find and understand the content they need. For PyPI this means: * Combining the docs currently located at [docs.pypi.org](https://docs.pypi.org/) and [pypi.org/help](https://pypi.org/help/) * Differentiating between content for consumers and producers ## Summary of recommendations We recommend updating the [PyPI documentation](https://docs.pypi.org/) to: * Develop a new structure (information architecture) to facilitate merging the documentation at [docs.pypi.org](https://docs.pypi.org/) and [pypi.org/help](https://pypi.org/help/) * Add a new ["Package Security" page](https://docs.google.com/document/d/1PtjIZU4G7yoZyHNSXrZwqm_Hg2PfEbC4Swl_La3tAI4/edit?usp=sharing) to explain security concepts (including attestations) to package consumers * Add a new "[Publishing to PyPI](https://docs.google.com/document/d/1UOj2WlfGOtGwFhusC0FRprUyBy8p_Y0S8uCK-mOKd9Q/edit?usp=sharing)" page, pointing users towards Trusted Publishing * Add a new "[Security and internals](https://docs.google.com/document/d/1a7BYF4QQ62Jbm8bcZ1RMacTLELKuNjAawj6paN48pm0/edit?usp=sharing)" page describing how PyPI mitigates security threats See https://docs.google.com/document/d/1vtkBTjKJ5ZAs8Qa8M6DBKzRYlxd5XjQ7FT6R3y7fBsI/edit?usp=sharing for all new proposed content. Feedback can be added on the Google Documents (please use comments), or shared on this GitHub issue.