chore(dev): warn from-source builders that syncthing auto-upgrades (#882

)

Some people may prefer to build from source for their own use. They
should be aware that the default behavior is to overwrite the binary
with a new downloaded binary when an upgrade is available.

Co-authored-by: André Colomb <[email protected]>

dev/building.rst

@@ -9,6 +9,12 @@ Building Syncthing
     of it. For all other purposes we recommend using the official binary
     releases instead.
 
+    If you still prefer to build Syncthing from source for your own use, be
+    aware that there is a built-in automatic upgrade mechanism that will
+    overwrite your built binary with a downloaded version. To avoid this, you
+    can use the ``--no-upgrade`` build flag (see below), but you will be
+    responsible for your own upgrades.
+
 Branches and Tags
 -----------------
 
@@ -103,7 +109,7 @@ The following ``build.go`` subcommands and options exist.
 ``go run build.go build``
   Builds just the named target, or ``syncthing`` by default, to the current
   directory. Use this when cross compiling, with parameters for what to cross
-  compile to: ``go run build.go -goos linux -goarch 386 build``.
+  compile to: ``go run build.go --goos linux --goarch 386 build``.
 
 ``go run build.go test``
   Runs the tests.
@@ -120,13 +126,13 @@ The following ``build.go`` subcommands and options exist.
   Creates a Syncthing zip dist file in the current directory. Assumes a
   Windows build.
 
-The options ``-no-upgrade``, ``-goos`` and ``-goarch`` can be given to
+The options ``--no-upgrade``, ``--goos`` and ``--goarch`` can be given to
 influence ``build``, ``tar`` and ``zip``. Examples:
 
-``go run build.go -goos linux -goarch 386 tar``
+``go run build.go --goos linux --goarch 386 tar``
   Builds a tar.gz distribution of Syncthing for linux-386.
 
-``go run build.go -goos windows -no-upgrade zip``
+``go run build.go --goos windows --no-upgrade zip``
   Builds a zip distribution of Syncthing for Windows (current architecture) with
   upgrading disabled.
 
@@ -155,12 +161,12 @@ If the tarball is from our build server it contains a file called
 ``RELEASE`` that informs the build system of the version being
 built. If you're building from a different source package, for example
 one automatically generated by GitHub, you must instead pass the
-``-version`` flag to ``build.go``.
+``--version`` flag to ``build.go``.
 
 If you are building something that will be installed as a package
-(Debian, RPM, ...) you almost certainly want to use ``-no-upgrade`` as
+(Debian, RPM, ...) you almost certainly want to use ``--no-upgrade`` as
 well to prevent the built in upgrade system from being activated.
 
-``go run build.go -version v0.10.26 -no-upgrade tar``
+``go run build.go --version v0.10.26 --no-upgrade tar``
   Builds a tar.gz distribution of Syncthing for the current OS/arch, tagged as
   ``v0.10.26``, with upgrades disabled.