Clarify use of startsecs/startretries and autorestart/exitcodes.

Closes #212

docs/configuration.rst

@@ -645,30 +645,19 @@ where specified.
 
   *Introduced*: 3.0
 
-``autorestart``
-
-  May be one of ``false``, ``unexpected``, or ``true``.  If ``false``,
-  the process will never be autorestarted.  If ``unexpected``, the
-  process will be restart when the program exits with an exit code
-  that is not one of the exit codes associated with this process'
-  configuration (see ``exitcodes``).  If ``true``, the process will be
-  unconditionally restarted when it exits, without regard to its exit
-  code.
-
-  *Default*: unexpected
-
-  *Required*:  No.
-
-  *Introduced*: 3.0
-
 ``startsecs``
 
   The total number of seconds which the program needs to stay running
-  after a startup to consider the start successful.  If the program
-  does not stay up for this many seconds after it has started, even if
-  it exits with an "expected" exit code (see ``exitcodes``), the
-  startup will be considered a failure.  Set to ``0`` to indicate that
-  the program needn't stay running for any particular amount of time.
+  after a startup to consider the start successful (moving the process
+  from the ``STARTING`` state to the ``RUNNING`` state).  Set to ``0``
+  to indicate that the program needn't stay running for any particular
+  amount of time.
+
+  .. note::
+
+      Even if a process exits with an "expected" exit code (see
+      ``exitcodes``), the start will still be considered a failure
+      if the process exits quicker than ``startsecs``.
 
   *Default*: 1
 
@@ -689,10 +678,38 @@ where specified.
 
   *Introduced*: 3.0
 
+``autorestart``
+
+  Specifies if :program:`supervisord` should automatically restart a
+  process if it exits when it is in the ``RUNNING`` state.  May be
+  one of ``false``, ``unexpected``, or ``true``.  If ``false``, the
+  process will not be autorestarted.  If ``unexpected``, the process
+  will be restart when the program exits with an exit code that is
+  not one of the exit codes associated with this process' configuration
+  (see ``exitcodes``).  If ``true``, the process will be unconditionally
+  restarted when it exits, without regard to its exit code.
+
+  .. note::
+
+      ``autorestart`` controls whether :program:`supervisord` will
+      autorestart a program if it exits after it has successfully started
+      up (the process is in the ``RUNNING`` state).
+
+      :program:`supervisord` has a different restart mechanism for when the
+      process is starting up (the process is in the ``STARTING`` state).
+      Retries during process startup are controlled by ``startsecs``
+      and ``startretries``.
+
+  *Default*: unexpected
+
+  *Required*:  No.
+
+  *Introduced*: 3.0
+
 ``exitcodes``
 
-  The list of "expected" exit codes for this program.  If the
-  ``autorestart`` parameter is set to ``unexpected``, and the process
+  The list of "expected" exit codes for this program used with ``autorestart``.
+  If the ``autorestart`` parameter is set to ``unexpected``, and the process
   exits in any other way than as a result of a supervisor stop
   request, :program:`supervisord` will restart the process if it exits
   with an exit code that is not defined in this list.

supervisor/skel/sample.conf

@@ -64,10 +64,10 @@ serverurl=unix:///tmp/supervisor.sock ; use a unix:// URL  for a unix socket
 ;umask=022                     ; umask for process (default None)
 ;priority=999                  ; the relative start priority (default 999)
 ;autostart=true                ; start at supervisord start (default: true)
-;autorestart=unexpected        ; whether/when to restart (default: unexpected)
-;startsecs=1                   ; number of secs prog must stay running (def. 1)
-;startretries=3                ; max # of serial start failures (default 3)
-;exitcodes=0,2                 ; 'expected' exit codes for process (default 0,2)
+;startsecs=1                   ; # of secs prog must stay up to be running (def. 1)
+;startretries=3                ; max # of serial start failures when starting (default 3)
+;autorestart=unexpected        ; when to restart if exited after running (def: unexpected)
+;exitcodes=0,2                 ; 'expected' exit codes used with autorestart (default 0,2)
 ;stopsignal=QUIT               ; signal used to kill process (default TERM)
 ;stopwaitsecs=10               ; max num secs to wait b4 SIGKILL (default 10)
 ;stopasgroup=false             ; send stop signal to the UNIX process group (default false)
@@ -102,10 +102,10 @@ serverurl=unix:///tmp/supervisor.sock ; use a unix:// URL  for a unix socket
 ;umask=022                     ; umask for process (default None)
 ;priority=-1                   ; the relative start priority (default -1)
 ;autostart=true                ; start at supervisord start (default: true)
-;autorestart=unexpected        ; whether/when to restart (default: unexpected)
-;startsecs=1                   ; number of secs prog must stay running (def. 1)
-;startretries=3                ; max # of serial start failures (default 3)
-;exitcodes=0,2                 ; 'expected' exit codes for process (default 0,2)
+;startsecs=1                   ; # of secs prog must stay up to be running (def. 1)
+;startretries=3                ; max # of serial start failures when starting (default 3)
+;autorestart=unexpected        ; autorestart if exited after running (def: unexpected)
+;exitcodes=0,2                 ; 'expected' exit codes used with autorestart (default 0,2)
 ;stopsignal=QUIT               ; signal used to kill process (default TERM)
 ;stopwaitsecs=10               ; max num secs to wait b4 SIGKILL (default 10)
 ;stopasgroup=false             ; send stop signal to the UNIX process group (default false)