Sync with latest Wiki content, syncthing -> Syncthing

2015-05-29 09:10:37 +02:00
parent cbf0766e86
commit 567d3dd0f5
27 changed files with 241 additions and 100 deletions
@@ -5,7 +5,7 @@ Building Syncthing

 .. note::
    You probably only need to go through the build process if you are going
-    to do development on syncthing or if you need to do a special packaging
+    to do development on Syncthing or if you need to do a special packaging
    of it. For all other purposes we recommend using the the official binary
    releases instead.

@@ -21,7 +21,7 @@ You should base your work on the ``master`` branch when doing your
 development. This branch is usually what will be going into the next
 release and always what pull requests should be based on.

-If you're looking to build and package a release of syncthing you should
+If you're looking to build and package a release of Syncthing you should
 instead use the latest tag (``vX.Y.Z``) as the contents of ``master``
 may be unstable and unsuitable for general consumption.

@@ -107,10 +107,10 @@ The following ``build.go`` subcommands and options exist.

 -  ``go run build.go test`` -- run the tests.

-  ``go run build.go tar`` -- create a syncthing tar.gz dist file in the
+-  ``go run build.go tar`` -- create a Syncthing tar.gz dist file in the
   current directory. Assumes a Unixy build.

-  ``go run build.go zip`` -- create a syncthing zip dist file in the
+-  ``go run build.go zip`` -- create a Syncthing zip dist file in the
   current directory. Assumes a Windows build.

 -  ``go run build.go  assets`` -- rebuild the compiled-in GUI assets.
@@ -124,10 +124,10 @@ The options ``-no-upgrade``, ``-goos`` and ``-goarch`` can be given to
 influence ``install``, ``build``, ``tar`` and ``zip``. Examples:

 -  ``go run build.go -goos linux -goarch 386 tar`` -- build a tar.gz
-   distribution of syncthing for linux-386.
+   distribution of Syncthing for linux-386.

 -  ``go run build.go -goos windows -no-upgrade zip`` -- build a zip
-   distribution of syncthing for Windows (current architecture) with
+   distribution of Syncthing for Windows (current architecture) with
   upgrading disabled.

 Building without Git
@@ -3,7 +3,7 @@
 Debugging Syncthing
 ===================

-There's a lot that happens behind the covers, and syncthing is generally
+There's a lot that happens behind the covers, and Syncthing is generally
 quite silent about it. A number of environment variables can be used to
 set the logging to verbose for various parts of the program, and to
 enable profiling.
@@ -63,13 +63,13 @@ can be used to enable this extra information on the normal logging
 level, without enabling any debugging: ``STTRACE=somethingnonexistent``
 for example.

-Under Unix (including Mac) the easiest way to run syncthing with an
+Under Unix (including Mac) the easiest way to run Syncthing with an
 environment variable set is to prepend the variable to the command line.
 I.e:

 ``$ STTRACE=model syncthing``

-On windows, it needs to be set prior to running syncthing.
+On windows, it needs to be set prior to running Syncthing.

 ::

@@ -11,12 +11,12 @@ Keys
 ====

 To understand device IDs we need to look at the underlying mechanisms.
-At first startup, syncthing will create an public/private key pair.
+At first startup, Syncthing will create an public/private key pair.

 Currently this is a 3072 bit RSA key. The keys are saved in the form of
 the private key (``key.pem``) and a self signed certificate
 (``cert.pem``). The self signing part doesn't actually add any security
-or functionality as far as syncthing is concerned but it enables the use
+or functionality as far as Syncthing is concerned but it enables the use
 of the keys in a standard TLS exchange.

 The typical certificate will look something like this, inspected with
@@ -93,8 +93,8 @@ Connection Establishment
 ========================

 So now we know what device IDs are, here's how they are used in
-syncthing. When you add a device ID to the syncthing configuration,
-syncthing will attempt to connect to that device. The first thing we
+Syncthing. When you add a device ID to the syncthing configuration,
+Syncthing will attempt to connect to that device. The first thing we
 need to do is figure out the IP and port to connect to. There's three
 possibilities here;

@@ -102,12 +102,12 @@ possibilities here;
   can equally well be a hostname, so if you have a static IP or a
   dynamic DNS setup this might be a good option.

-  Using local discovery, if enabled. Every syncthing instance on a LAN
+-  Using local discovery, if enabled. Every Syncthing instance on a LAN
   periodically broadcasts information about itself (device ID, address,
   port number). If we've seen one of these broadcasts for a given
   device ID that's where we try to connect.

-  Using global discovery, if enabled. Every syncthing instance
+-  Using global discovery, if enabled. Every Syncthing instance
   announces itself to the global discovery service (device ID and
   external port number - the internal address is not announced to the
   global server). If we don't have a static address and haven't seen
@@ -172,7 +172,7 @@ here:
 It's also worth noting that the property of SHA-256 that we are using is
 not simply collision resistance but resistance to a preimage attack.
 I.e. even if you can find two messages that result in a hash collision
-that doesn't help you attack syncthing (or TLS in general). You need to
+that doesn't help you attack Syncthing (or TLS in general). You need to
 create a message that hashes to exactly the hash that my certificate
 already has or you won't get in.

@@ -231,7 +231,7 @@ are various possible solutions;
   confirm that this is correct.").

 -  Use shorter device IDs with an out of band authentication, a la
-   Bluetooth pairing. You enter a one time PIN into syncthing and give
+   Bluetooth pairing. You enter a one time PIN into Syncthing and give
   that PIN plus a short device ID to another user. On initial connect,
   both sides verify that the other knows the correct PIN before
   accepting the connection.
@@ -26,15 +26,16 @@ error", "Rendered moot by #123" and so on. We don't use the "invalid" or

 -  **docs** - Something requires documenting.

-  **easy** - This could be easily fixed, probably an hours work or
-   less.
+-  **easy** - This could be easily fixed, probably an hour's work or
+   less. These issues are good starting points for new contributors.

 -  **enhancement** - This is a new feature or an improvement of some
   kind, as opposed to a problem (bug).

 -  **help-wanted** - The core team can't or won't do this, but someone
   else is welcome to. This does not mean that help is not wanted on the
-   *other* issues. You can see this as a soft ``wontfix``.
+   *other* issues. You can see this as a soft ``wontfix``. (A hard
+   ``wontfix`` is simply a close with a short explanation why.)

 -  **pr-bugfix** - This pull request *fixes* a bug. This is different
   from the ``bug`` label, as there may also be pull requests with for
@@ -48,3 +49,39 @@ error", "Rendered moot by #123" and so on. We don't use the "invalid" or
   requires more discussion.

 -  **protocol** - This requires a change to the protocol.
+
+Milestone
+---------
+
+There are milestones for major and sometimes minor versions. An issues
+being assigned to a milestone means it is a blocker - the release can't
+be made without the issue being closed. Issues not assigned to a
+milestone can be handled whenever.
+
+Assignee
+--------
+
+Users can be assigned to issues. We don't usually do so. Sometimes
+someone assigns themself to an issue to indicate "I'm working on this"
+to avoid others doing so too. It's not mandatory.
+
+Locking
+-------
+
+We don't normally lock issues (prevent further discussion on them).
+There are some exceptions though;
+
+-  "Popular" issues that attract lots of "me too" and "+1" comments.
+   These are noise and annoy people with useless notifications via mail
+   and in the Github interface. Once the issue is clear and it suffers
+   from this symptom I may lock it.
+
+-  Contentious bikeshedding discussions. After two sides in a discussion
+   have clarified their points, there is no point arguing endlessly
+   about it. As above, this may get closed.
+
+-  Duplicates. Once an issue has been identified as a duplicate of
+   another issue, it may be locked to prevent further discussion there.
+   The intention is to move the discussion to the other (referenced)
+   issue, while someone just doing a search and jumping on the first
+   match might otherwise resurrect discussion in the duplicate.
@@ -4,7 +4,7 @@ Creating a Release
 Prerequisites
 -------------

-  Push access to the syncthing repo, for pushing a new tag.
+-  Push access to the ``syncthing`` repo, for pushing a new tag.

 -  SSH account on build server, member of the ``jenkins`` group, for
   accessing and signing the releases.
@@ -3,7 +3,7 @@ REST API

 Syncthing exposes a REST interface over HTTP on the GUI port. This is
 used by the GUI code (Javascript) and can be used by other processes
-wishing to control syncthing. In most cases both the input and output
+wishing to control Syncthing. In most cases both the input and output
 data is in JSON format. The interface is subject to change.

 API Key