1606753 - Bootstrap script: Artifact Build instructions re: mozconfig file could be more clear

Status: NEW

(Firefox Build System :: Bootstrap Configuration, enhancement)

Description

[Victoria Wang [:victoria]]

Currently, this is what prints at the end of the boostrap script for artifact builds:

Your system should be ready to build Firefox for Desktop Artifact Mode!

To build Firefox for Desktop Artifact Mode, please restart the shell (Start a new terminal window)

Paste the lines between the chevrons (>>> and <<<) into your
$topsrcdir/mozconfig file, or create the file if it does not exist:

>>>
# Automatically download and use compiled C++ components:
ac_add_options --enable-artifact-builds
<<<

We've found that DevTools contributors miss this last step about mozconfig, and I myself found it a bit confusing that this step was needed after the script already said "Your system should be ready!"

I would suggest this instead:

Boostrap complete. As a final step, paste the lines between the chevrons (>>> and <<<) 
into your $topsrcdir/mozconfig file, or create the file if it does not exist:

>>>
# Automatically download and use compiled C++ components:
ac_add_options --enable-artifact-builds
<<<

Your system will now be ready to build Firefox for Desktop Artifact Mode!

Please restart the shell (start a new terminal window) before continuing.

Here is a shorter version which would be my favorite - I think the chevrons are a bit scary, so this seems friendlier to me :)

Boostrap complete! As a final step, create a file called mozconfig and paste this line into it:

ac_add_options --enable-artifact-builds

Your system will now be ready to build Firefox for Desktop Artifact Mode! Please start a new 
terminal window before continuing.

Comment 1

[Nathan Froyd [:froydnj]]

Thanks for filing this! Anything to reduce the verbosity of bootstrap output would be appreciated.

I have small tweaks to your proposed wording:

Bootstrap complete! As a final step, create a file called mozconfig and paste the following line into it:

ac_add_options --enable-artifact-builds

Your system will then be ready to build Firefox for Desktop Artifact Mode! Please start a new 
terminal window before continuing.

I'm a little unsure about two things:

1. Do we still want to say $topsrcdir/mozconfig? I think saying "create a file called mozconfig" might prompt somebody to create it in the wrong place.
2. Removing the chevrons seems fine, but we use chevrons in lots of other places, and it'd be nice to be consistent everywhere.

Comment 2

[Victoria Wang [:victoria]]

Thanks for welcoming this bug :D. So, I guess the $topsrcdir/file thing seems confusing to me even with my (old rails dev and current CSS) coding experience, so maybe we could say this:

Bootstrap complete. As a final step, create a file called mozconfig at the root of your mozilla-central directory and paste the following line into it:

RE: chevrons,

I know they're useful for indicating multiple lines that need to be copied. Maybe in the short term, we can continue to use that in those cases, and just simplify this one case of a single copyable line?

In the long them, I think it would be ideal if we could 'indent' blocks that need to be copied, like this:

Paste the following:

 stuff
 to
 copy

etc...

Though I don't know if there's a way to do that without adding undesirable spaces to the clipboard.

Comment 3

[Victoria Wang [:victoria]]

Hello! Just wanted to check in on this. I'm working on docs again because we are starting to get a wave of new contributors with GSoC :).

Are changes to the bootstrap script live once they're landed to "Nightly," or are they tied to the trains?

Comment 4

[Nathan Froyd [:froydnj]]

(In reply to Victoria Wang [:victoria] from comment #3)

Hello! Just wanted to check in on this. I'm working on docs again because we are starting to get a wave of new contributors with GSoC :).

Are changes to the bootstrap script live once they're landed to "Nightly," or are they tied to the trains?

Changes to the bootstrap script are live as soon they get merged to mozilla-central!

Comment 5

[Victoria Wang [:victoria]]

That's great! Did you have thoughts on comment #2? Or even as a first pass, my original verbose suggestion would help a lot, I think.

Comment 6

[Nathan Froyd [:froydnj]]

(In reply to Victoria Wang [:victoria] from comment #5)

That's great! Did you have thoughts on comment #2? Or even as a first pass, my original verbose suggestion would help a lot, I think.

Sorry for not responding to this sooner! Didn't get needinfo'd and it dropped off my radar.

The proposed text for mozconfig changes sounds great. I think we can forego the chevrons for single-line changes. Copy-and-pasting indented lines ought to work in the longer term, but it'd be good to verify that first.

Comment 7

[Victoria Wang [:victoria]]

Thanks Nathan! So, to summarize, this is what the final text should look like:

Bootstrap complete. As a final step, create a file called mozconfig at the root of your 
mozilla-central directory and paste the following line into it:

ac_add_options --enable-artifact-builds

Your system will then be ready to build Firefox for Desktop Artifact Mode! Please start 
a new terminal window before continuing.

I'll see if anyone wants to work on this.

Comment 8

[Molly Howell (she/her) (mostly inactive)]

I had a quick look at this because on the surface it sounded like an easy patch that I could just knock out, but I found a few complications:

1. The current message is actually printed out in three parts. The "your system should be ready" line comes from here, the bit about restarting the shell is the next block right after that line, and then the mozconfig instructions come from here. It's not immediately clear to me what the best way to unify those places into the one new message is, someone with experience in the bootstrap code should probably weigh in on that.
2. The aforementioned bit about restarting the shell is conditional, it only appears when we know something happened that really does require restarting the shell, so we also have to account for that (or alternatively decide to switch to always showing that message even when it isn't necessary).
3. The Android artifact bootstrap has its own version of the mozconfig instructions, which require pasting in more than one line.