1687980 - Clean quick-start docs for Win/Mac/Linux

Status: RESOLVED FIXED

(Developer Infrastructure :: Source Documentation, enhancement)

Description

[Mitchell Hentges [:mhentges] 🦀]

• We recommend installing an old Mac SDK, but that's not needed anymore
• Mac docs are generally in the wrong order
• Windows docs have unimportant information highlighted, and relevant infos blend into the background
• Linux docs have unnecessary mozconfig tweaking
• Chatter about the bootstrap script is somewhat out-of-date

🔧

Comment 1

[Shivam Singhal [ :championshuttler ]]

Mitchell, there is one patch landed recently to upgrade the macos version in docs https://phabricator.services.mozilla.com/D100591.

Comment 2

[Mitchell Hentges [:mhentges] 🦀]

Hey Shivam, though we use 10.12 in CI, developers should be able to use the SDK that ships with XCode from the App Store, rather than downloading a specific version.

Glandium briefly mentioned this in a patch here.

Oh boy, I didn't even know this doc existed, but I'm not sure it should even talk about a specific SDK in such a way.

Comment 3

[Mike Hommey [:glandium]]

The mac SDK part is bug 1680441

Comment 4

[Mitchell Hentges [:mhentges] 🦀]

Attachment: Bug 1687980: Make macOS quickstart docs more concise

• Removes duplicated information (are commands the same as what you get
  with the Windows CMD.EXE shell? No, and also no).
• Moves MozillaBuild information to
  https://wiki.mozilla.org/MozillaBuild.
• Removes obsolete troubleshooting steps
• Moves redistribution tips to redistribution docs.
• Removes unnecessarily verbose information.

Comment 5

[Mitchell Hentges [:mhentges] 🦀]

Attachment: Bug 1687980: Make Windows quickstart docs more concise

• Puts the docs in order, so that contributors aren't jumping to the
  middle of the page to install system tools, then back to the top to
  clone Firefox.
• Removes docs on MacPorts since it's being removed in bug 1688263.
• Removes step to manually install brew packages since that happens
  automatically in bootstrap now.
• Simplifies mercurial installation docs
• Removes unnecessary mozconfig-tweaking instructions
• Removes almost-always-unnecessary DEFINE and troubleshooting
  information.

Depends on D102973

Comment 6

[Mitchell Hentges [:mhentges] 🦀]

Attachment: Bug 1687980: Make Linux quickstart docs more concise

• Removes duplicated information
• Removes unnecessary extra details (e.g.: how pyenv works - that's
  documented in pyenv docs)
• Recommends the standalone bootstrap script
• Removes unnecessary mozconfig instructions
• Removes unnecessary per-distro information

Depends on D102974

Comment 7

[Mitchell Hentges [:mhentges] 🦀]

Attachment: Screenshot from 2021-02-01 16-08-40.png

[Personal notes to track the work here]

• The "Getting Set Up To Work On The Firefox Codebase" shouldn't show subsections for each machine
• We should clarify somewhere that ./mach bootstrap only works on up-to-date revisions of central, and not tarballs/ESR/etc

Comment 8

[Mitchell Hentges [:mhentges] 🦀]

Attachment: Bug 1687980: Simplify "Getting Set Up" page

When a user is at the top-level "Getting Set Up" page, they should be
shown which path to take (Windows/Mac/Linux) without redundantly showing
the platform-specific technicalities.

Depends on D102975

Comment 9

[Mitchell Hentges [:mhentges] 🦀]

Attachment: Bug 1687980: Remove obsolete Fedora 19/20 32bit setup docs

Fedora 19 and 20 were released in 2013. If these docs haven't been
adjusted for modern Fedora, they're probably out-of-date.

Depends on D104099

Comment 10

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/e4a58d499e2f
Make macOS quickstart docs more concise r=sylvestre,mhoye
https://hg.mozilla.org/integration/autoland/rev/d5ac436543a8
Make Windows quickstart docs more concise r=mhoye,sylvestre,andi
https://hg.mozilla.org/integration/autoland/rev/59a4c66dc2f8
Make Linux quickstart docs more concise r=mhoye,sylvestre
https://hg.mozilla.org/integration/autoland/rev/245f01688f71
Simplify "Getting Set Up" page r=mhoye,firefox-build-system-reviewers,glandium,sylvestre,andi
https://hg.mozilla.org/integration/autoland/rev/f94b12334668
Remove obsolete Fedora 19/20 32bit setup docs r=sylvestre

Comment 11

[Andreea Pavel [:apavel]]

https://hg.mozilla.org/mozilla-central/rev/e4a58d499e2f
https://hg.mozilla.org/mozilla-central/rev/d5ac436543a8
https://hg.mozilla.org/mozilla-central/rev/59a4c66dc2f8
https://hg.mozilla.org/mozilla-central/rev/245f01688f71
https://hg.mozilla.org/mozilla-central/rev/f94b12334668