1684460 - Provide complete and correct instructions for fetching and building source

Status: UNCONFIRMED

(SeaMonkey :: Release Engineering, defect)

Description

[Tristan Miller]

I package SeaMonkey for openSUSE but as of 2.53.6b1 my usual checkout + build process is no longer working due to the removal of client.mk from the base directory. I'm trying to figure out the current correct way of fetching the source from version control and building it, but the documentation for this seems to be scattered, contradictory, incorrect, and incomplete. It would be helpful if a complete and correct version of the instructions could be put in one place. I'll try to provide an overview of the interrelated problems with the documentation, but please excuse me if this gets a bit hairy.

Let's start at the README, because this directly linked from the release page with the description "The README file explains how to pull SeaMonkey 2.53.6 Beta 1 from the source repository."

The very beginning of the README gives the following instructions for checking out the sources from version control:

These binaries were all built from SeaMonkey's 2.53 GitLab repositories, off
the 2_53_6_beta_01 branch, and Mozilla's repositories for the extensions, off the
default branch, with the following commands used to obtain the sources:

git clone -b 2_53_6_beta_01 https://gitlab.com/seamonkey-project/seamonkey-2.53-comm.git comm-253
cd comm-253
git clone -b 2_53_6_beta_01 https://gitlab.com/seamonkey-project/seamonkey-2.53-mozilla.git mozilla
cd mozilla/extensions
hg clone https://hg.mozilla.org/chatzilla irc
hg clone https://hg.mozilla.org/dom-inspector inspector

These commands work fine, insofar as they don't result in any errors. However, the README goes on to say that

A source code tarball with the contents of all the repositories, ready to
build, is available for download from the source/ subdirectory here on FTP.

There are a couple problems with this statement:

1. It refers to getting files by FTP, but all the download links on the release page are to an HTTP server. Maybe an official FTP server still exists somewhere, but if so, it doesn't seem to be the preferred way of downloading the tarball any more, and in any case these instructions don't help users who are looking for the tarball on the web server instead. Rather than writing "here on FTP", it would be better to provide the exact URL(s) of the source/ subdirectory. In the case of 2.53.6b1, this is presumably https://archive.mozilla.org/pub/seamonkey/releases/2.53.6b1/source/ for the tarball hosted on the web server.

2. The tarball hosted on the web server has a different directory structure than the one produced with the instructions at the beginning of the README. As far as I can tell, it was produced by first checking out the seamonkey-2.53-mozilla repository and then checking out the seamonkey-2.53-comm repository in a subdirectory, rather than the other way around. If this is the correct way of doing things now, then the instructions in the README need to be updated. If it's not the correct way of doing things, then the source tarball needs to be restructured. If both ways are correct, then the README needs to mention this (and to explain why it chose to provide instructions that result in a source tree that differs so conspicuously from the official source tarball).

The README goes on with the following instructions for building SeaMonkey:

Read https://www.seamonkey-project.org/dev/ for instructions on how to build
your own copy of SeaMonkey.

This statement is problematic because that page contains no instructions at all for building SeaMonkey. The closest hint it provides is to to check the Mozilla developer guide:

Even though we are independent from Mozilla, as we're based on the same framework as Firefox, most of the mozilla.org developer pages also apply to SeaMonkey, there's also content there that explains how to get the comm-central source code, which includes the current SeaMonkey development code.

Unfortunately, the link titled "how to get the comm-central source code" goes to a nonexistent page. The previous link, "mozilla.org developer pages", is a bit more useful as it leads to a page with a Build Instructions link described as "How to build Firefox, Thunderbird, SeaMonkey, or other Mozilla applications." That page in turn links to a Simple Seamonkey build page that purports to contain instructions for checking out the source, creating a basic .mozconfig file, and building the application. But there are two problems with these instructions:

1. The instructions for checking out the source are completely different from those contained in the SeaMonkey README. Following these instructions results in yet another source tree, different from both the one you get from following the README instructions and the one from the official source tarball. Perhaps this is because the instructions on MDN are for checking out the master branch rather than the branch/tag for a particular version of SeaMonkey, but even if so, this doesn't help people who came to these instructions from the README.

2. The instructions don't actually work; they say to run python client.py checkout but the repository doesn't contain any client.py file in the base directory. (See mdn/content Issue 725.)

In summary, it would be helpful if the following could be fixed:

1. The instructions for checking out the source code given in the README should result in a source tree that bears at least a passing resemblance to the one you get from the official source tarball.

2. The instructions in the README should be more specific about where to obtain the source tarballs (code, l10n, language packs) rather than just saying "here on FTP".

3. The instructions in the README and at https://www.seamonkey-project.org/dev/ should refer to a page that contains complete and correct build instructions.

4. If said build instructions are supposed to live at the Simple Seamonkey build on MDN, then those instructions should be modified so that (a) the source checkout instructions are correct, and (b) the build instructions are comprehensible and correct for someone who checked out the source for a particular version of SeaMonkey using the the very different method specified in the SeaMonkey README.

Comment 1

[Tristan Miller]

I've just realized that this is a partial duplicate of Bug 1620789, though that report is only about the instructions on the SeaMonkey website whereas this report is wider-ranging and makes reference to specific problems elsewhere, including the README and MDN. Not sure if you want to keep both reports open or dupe one to another.

Comment 2

[Ian Neal]

The README corrections should be covered under Bug 1682424 - "here" refers to where the README file is found (in this case https://archive.mozilla.org/pub/seamonkey/releases/2.53.6b1/), the FTP was left over from when it was both ftp and http(s).

As you say Bug 1620789 covers the instructions on the SM website.

This bug should probably remain open to cover what needs to be done with the information on MDN. There seems to have been a lot of changes on how MDN is organised and updated, so need to consider what to do with that content.

Comment 3

[Edmund Wong (:ewong)]

(In reply to Ian Neal from comment #2)

The README corrections should be covered under Bug 1682424 - "here" refers to where the README file is found (in this case https://archive.mozilla.org/pub/seamonkey/releases/2.53.6b1/), the FTP was left over from when it was both ftp and http(s).

As you say Bug 1620789 covers the instructions on the SM website.

This bug should probably remain open to cover what needs to be done with the information on MDN. There seems to have been a lot of changes on how MDN is organised and updated, so need to consider what to do with that content.

I don't think we should put anything on MDN and have the instructions posted somewhere on our website (or somewhere else). (Just my $0.02)