Closed Bug 1689965 Opened 10 months ago Closed 3 months ago

Documentation for unbundling mercurial bundles is unclear

Categories

(Firefox Build System :: Documentation Infrastructure, defect)

defect

Tracking

(firefox93 fixed)

RESOLVED FIXED
93 Branch
Tracking Status
firefox93 --- fixed

People

(Reporter: standard8, Assigned: arai)

Details

Attachments

(2 files)

Someone was asking a question on the introduction channel on Matrix and I looked at what they were quoting, and found it unclear as well.

The setting up the repository section currently says:

  1. Un-bundle the bundle file to that repository:

To use the below command in Windows, export the \path\to\hg and invoke the command from command prompt.

On Linux/Mac click on the properties of the file and you can find the path. In case the name of the file is not bundle.hg rename it.

<command details>

The first part about Windows, I'm not sure what it is referring to. It almost seems like it is saying to ensure hg is in the path, but in step 1 the reader would have already used hg. If it is referring to how to obtain the path for where the bundle was downloaded to, then we need to make that clearer.

The second part about Linux/Mac is also not really clear. On Mac there's not an easy way that I knew about until just now - you have to go to finder, find it, then right-click press alt and copy as pathname, or drag and drop the file to the terminal window to get the path.

Also, I don't think we need to specifically rename to bundle.hg. Mercurial should be able to cope with whatever you throw at it - it is just a path to a file.

Based on what I think we're trying to convey, I would suggest altering the section text to something like:

2. Unbundle the bundle file to that repository:

Use the following commands to unbundle the file. You need to replace `/path/to/your/bundle.hg` with the real path of the file.

On Windows to get the path of the file you ...

On Mac to get the path of the file you can click the downloads button in Firefox, select "Show in Finder", then right-click on the file. Press the option key and select `Copy "<something.hg>` as Pathname`.

On Linux to get the path of the file you ...

cd mozilla-central
hg unbundle /path/to/your/bundle.hg

Get comfortable. Grab a coffee (or your favorite tasty beverage). Maybe a nap. This unbundling process is going to take quite a lot of time.

We might want to split how to get the path of the file on different platforms out to a separate doc/section, so that it can be referenced from different documents, it'd also make this section simpler for those that already know how to get the path.

I think it's better just moving the file in the parent directory and renaming it to bundle.hg, and using relative path in the command (../bundle.hg).
that way you don't have to explain how to get the path, for each OS.

Assignee: nobody → arai.unmht
Status: NEW → ASSIGNED
Pushed by arai_a@mac.com:
https://hg.mozilla.org/integration/autoland/rev/15fe03027a3d
Part 1: Remove unnecessary paragraph about path to hg. r=sylvestre
https://hg.mozilla.org/integration/autoland/rev/db611ca2817e
Part 2: Use relative path in order to avoid OS-specific description around getting path to the file. r=sylvestre
Status: ASSIGNED → RESOLVED
Closed: 3 months ago
Resolution: --- → FIXED
Target Milestone: --- → 93 Branch
You need to log in before you can comment on or make changes to this bug.