wiki:Meetings/MacPortsMeeting2018/Documentation

Version 3 (modified by neverpanic (Clemens Lang), 6 years ago) (diff)

--

Documentation

Documentation Location

We currently have documentation in a myriad of locations, such as

  • the Guide
  • manpages
  • Trac wiki pages
  • website

This situation is not ideal, since it is not clear which documentation goes where and creates inconsistencies between multiple locations.

Multiple documentation locations may be justifiable, for example when separating user from developers documentation.

We should move to a single location for documentation that is more easily editable than the guide currently is, but otherwise collects all information that is currently spread over the guide, wiki pages and the website.

Documentation Content

Improving the Installation User Experience

  • The download page should auto-detect the user's operating system and already offer the correct download.
  • To satisfy the need for a "one-line-copy-paste-auto-install" while avoiding the dreaded "curl | sudo sh", we could offer a single line similar to xcode-select --install && curl -OL "$pkgurl" && sudo installer -package "$pkgfile" -target /

Documenting MacPorts' Advantages

The documentation should explain MacPorts' advantages and why certain decision have been made (and why they are good).

Privilege Separation (aka 'MacPorts requires sudo/root')

MacPorts does not run builds as your user, but will switch to a separate, unprivileged macports user when building. This prevents builds from accidentally modifying files in, for example, your home directory.

MacPorts also runs its builds inside a sandbox that will prevent them from modifying files outside of the places where MacPorts supports modifications to ensure a rogue build system will not wreak havoc on your system.

Files installed by MacPorts are owned by root, so that they cannot be changed by software run under your user account. This gives you the guarantee that the files installed by MacPorts are not changed without your knowledge.

'Why do you need me to modify $PATH'