1454350 - Simplify DevTools documentation to use only Mercurial

Status: RESOLVED FIXED

(DevTools :: General, enhancement)

Description

[Belén [:ladybenko]]

In the "Contributing" guide of the DevTools docs, there are multiple references to Git. However, since Mercurial is what it's better supported, we should avoid confusing people and refer only to Mercurial.

Comment 1

[Belén [:ladybenko]]

Attachment: Bug 1454350 - simplify devtools docs to use mercurial.

Review commit: https://reviewboard.mozilla.org/r/237136/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/237136/

Comment 2

[Soledad Penades [:sole] [:spenades]]

Comment on attachment 8968435 [details]
Bug 1454350 - simplify devtools docs to use mercurial.

https://reviewboard.mozilla.org/r/237136/#review242948

Very good first go at this, needs a couple fixes and it'll be good to go! Thank you for helping new developers! :)

::: devtools/docs/contributing/making-prs.md:7
(Diff revision 1)
> -
>  ## Creating a patch
>  
>  To create a patch you need to first commit your changes and then export them to a patch file.
>  
>  With Mercurial:

Since we're using only Mercurial officially, maybe this line can be deleted.

::: devtools/docs/contributing/making-prs.md:9
(Diff revision 1)
>  
>  With Mercurial:
> -* `hg commit -m 'your commit message'`
> -* `hg export > /path/to/your/patch`
>  
> -With Git, the process is similar, but you first need to add an alias to create Mercurial-style patches. Have a look at [the detailed documentation](https://developer.mozilla.org/en-US/docs/Tools/Contributing#Creating_a_patch_to_check_in).
> +1. `hg commit -m 'your commit message'`

Why are there two `1. `? Could we have a single block of code as it makes things easier to copy and paste? E.g.

```bash
hg commit -m 'your commit message'
hg export > /path/to/your/patch
```

::: devtools/docs/contributing/making-prs.md:26
(Diff revision 1)
>  
>  You can also take a look at the [Code Review Checklist](./code-reviews.md) as it contains a list of checks that your reviewer is likely to go over when reviewing your code.
>  
>  ## Squashing commits
>  
> -Sometimes you may be asked to squash your commits. Squashing means merging multiple commits into one in case you created multiple commits while working on a bug. Squashing bugs is easy with steps listed below for both git and mercurial.
> +Sometimes you may be asked to squash your commits. Squashing means merging multiple commits into one in case you created multiple commits while working on a bug. Squashing bugs is easy with steps listed below for Mercurial.

It feels like "Squashing bugs is easy with steps listed below for Mercurial." is superfluous, what do you think?

::: devtools/docs/contributing/making-prs.md:28
(Diff revision 1)
>  
> -Sometimes you may be asked to squash your commits. Squashing means merging multiple commits into one in case you created multiple commits while working on a bug. Squashing bugs is easy with steps listed below for both git and mercurial.
> +Sometimes you may be asked to squash your commits. Squashing means merging multiple commits into one in case you created multiple commits while working on a bug. Squashing bugs is easy with steps listed below for Mercurial.
> -
> -### With Mercurial:
>  
>  We will use the histedit extension for squashing commits in Mercurial. You can check if this extension is enabled in your Mercurial following these steps:

in your Mercurial... installation? Feels like it's missing that word

::: devtools/docs/contributing/making-prs.md:29
(Diff revision 1)
> -Sometimes you may be asked to squash your commits. Squashing means merging multiple commits into one in case you created multiple commits while working on a bug. Squashing bugs is easy with steps listed below for both git and mercurial.
> +Sometimes you may be asked to squash your commits. Squashing means merging multiple commits into one in case you created multiple commits while working on a bug. Squashing bugs is easy with steps listed below for Mercurial.
> -
> -### With Mercurial:
>  
>  We will use the histedit extension for squashing commits in Mercurial. You can check if this extension is enabled in your Mercurial following these steps:
>  * Open `.hgrc` (default configuration file of mercurial) located in the home directory on Linux/OSX, using your favourite editor.

Capital M Mercurial?

Also I wonder if we can point to where the conf file is in Windows, or at least leave a <!--TODO--> comment and file a bug so someone can contribute to this

::: devtools/docs/contributing/making-prs.md:43
(Diff revision 1)
>  ```
>  pick 3bd22d1cc59a 0 "First-Commit-Message"
>  pick 81c4d40e57d3 1 "Second-Commit-Message"
>  ```
>  
> -These lines represent your commits. Suppose we want to merge 81c4d40e57d3 to 3bd22d1cc59a. Then replace **pick** in front of 81c4d40e57d3 with **fold** (or simply 'f'). Save the changes.
> +These lines represent your commits. Suppose we want to merge `81c4d40e57d3` to `3bd22d1cc59a`. Then replace **pick** in front of `81c4d40e57d3` with **fold** (or simply 'f'). Save the changes.

Nice formatting!

::: devtools/docs/contributing/making-prs.md:45
(Diff revision 1)
>  pick 81c4d40e57d3 1 "Second-Commit-Message"
>  ```
>  
> -These lines represent your commits. Suppose we want to merge 81c4d40e57d3 to 3bd22d1cc59a. Then replace **pick** in front of 81c4d40e57d3 with **fold** (or simply 'f'). Save the changes.
> +These lines represent your commits. Suppose we want to merge `81c4d40e57d3` to `3bd22d1cc59a`. Then replace **pick** in front of `81c4d40e57d3` with **fold** (or simply 'f'). Save the changes.
>  
> -You will see that 81c4d40e57d3 has been combined with 3bd22d1cc59a. You can verify this using `hg log` command.
> +You will see that `81c4d40e57d3` has been combined with `3bd22d1cc59a`. You can verify this using `hg log` command.

Add "the" before `hg log` command. Otherwise it sounds very robotic!

::: devtools/docs/contributing/making-prs.md:47
(Diff revision 1)
>  
> -These lines represent your commits. Suppose we want to merge 81c4d40e57d3 to 3bd22d1cc59a. Then replace **pick** in front of 81c4d40e57d3 with **fold** (or simply 'f'). Save the changes.
> +These lines represent your commits. Suppose we want to merge `81c4d40e57d3` to `3bd22d1cc59a`. Then replace **pick** in front of `81c4d40e57d3` with **fold** (or simply 'f'). Save the changes.
>  
> -You will see that 81c4d40e57d3 has been combined with 3bd22d1cc59a. You can verify this using `hg log` command.
> +You will see that `81c4d40e57d3` has been combined with `3bd22d1cc59a`. You can verify this using `hg log` command.
>  
>  You can use fold to as many commits you want and they will be combined with the first commit above them which does not use fold.

It looks like a word is missing here and the sentence doesn't quite make sense. "You can fold to [missing word here???] as many commits" - I think it can be rewritten as "You can fold as many commits as you want, and they will be combined with the first commit above them which does not use `fold`".

::: devtools/docs/getting-started/build.md:14
(Diff revision 1)
>    * [Artifact builds](#building-even-faster-with-artifact-builds) for even faster builds
>    * [Maybe you don't even need to build](#maybe-you-dont-even-need-to-build)
>  
>  ## Getting the code
>  
> -The code is officially hosted on [a Mercurial repository](https://hg.mozilla.org/mozilla-central/). Despair not! There are ways of accessing this via git. We will explain this too.
> +The code is officially hosted on [a Mercurial repository](https://hg.mozilla.org/mozilla-central/). It takes a long time, because the repository is **B I G**. So be prepared to be patient.

It takes a long time... to clone

::: devtools/docs/getting-started/build.md:23
(Diff revision 1)
> -There is a tool called [git-cinnabar](https://github.com/glandium/git-cinnabar/) that lets you use git on top of a Mercurial repository. There's a bit of setup involved, so we've written [a script to automate](https://github.com/sole/cinnabarify) installing `git-cinnabar` and obtaining the code.
> -
>  ## Building and running locally
>  
> -Whatever method you used to obtain the code, the build step is the same. Fortunately, the Firefox team has made a very good job of automating this with bootstrap scripts and putting [documentation](https://developer.mozilla.org/En/Simple_Firefox_build) together.
> +Fortunately, the Firefox team has made a very good job of automating the building process with bootstrap scripts and putting [documentation](https://developer.mozilla.org/En/Simple_Firefox_build) together.
>  

Here, should it include the configure step?

Since you had issues setting it up without it... I don't think it can *hurt* to run it for the first time, and it might save people some frustration.

::: devtools/docs/getting-started/build.md:105
(Diff revision 1)
>  # 5. edit JS files on the `devtools` folder, save
>  # 6. Back to step 2!
>  ./mach run
>  ```
>  
>  While not as fast as the average "save file and reload the website" *web development workflow*, or newer workflows such as React's reloading, this can still be quite fast. 

I think there's a trailing space here (gasp!) sorry!--- it is rendered in furious red in MozReview

Comment 3

[Belén [:ladybenko]]

Comment on attachment 8968435 [details]
Bug 1454350 - simplify devtools docs to use mercurial.

Review request updated; see interdiff: https://reviewboard.mozilla.org/r/237136/diff/1-2/

Comment 4

[Soledad Penades [:sole] [:spenades]]

Comment on attachment 8968435 [details]
Bug 1454350 - simplify devtools docs to use mercurial.

https://reviewboard.mozilla.org/r/237136/#review243082

Sorry, couple more fixes but then it should be really good to go!

::: devtools/docs/contributing/making-prs.md:8
(Diff revision 2)
>  ## Creating a patch
>  
>  To create a patch you need to first commit your changes and then export them to a patch file.
>  
> -With Mercurial:
> -* `hg commit -m 'your commit message'`
> +```
> +`hg commit -m 'your commit message'`

remove the ` ` on each line inside the block :)

::: devtools/docs/getting-started/build.md:6
(Diff revision 2)
>  # Set up to build Firefox Developer Tools
>  
>  These are the steps we're going to look at:
>  
>  * [Getting the code](#getting-the-code)
> -  * [using Mercurial](#using-mercurial-hg)
> +  * [Using Mercurial](#using-mercurial-hg)

Sorry to be super picky, but maybe we want to remove this option since there's no specific section for Mercurial now!

::: devtools/docs/getting-started/build.md:113
(Diff revision 2)
>  # 5. edit JS files on the `devtools` folder, save
>  # 6. Back to step 2!
>  ./mach run
>  ```
>  
>  While not as fast as the average "save file and reload the website" *web development workflow*, or newer workflows such as React's reloading, this can still be quite fast. 

still has a trailing space?

Comment 5

[Belén [:ladybenko]]

Comment on attachment 8968435 [details]
Bug 1454350 - simplify devtools docs to use mercurial.

Review request updated; see interdiff: https://reviewboard.mozilla.org/r/237136/diff/2-3/

Comment 6

[Soledad Penades [:sole] [:spenades]]

Comment on attachment 8968435 [details]
Bug 1454350 - simplify devtools docs to use mercurial.

https://reviewboard.mozilla.org/r/237136/#review243646

Fantastic! this is perfect now. Thank you!

Comment 7

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/9003972112e3
simplify devtools docs to use mercurial. r=sole

Comment 8

[Cosmin Sabou [:CosminS]]

https://hg.mozilla.org/mozilla-central/rev/9003972112e3