Merge pull request #160 from oleg-nenashev/master

Documentation updates towards 2.0

CHANGELOG.md

@@ -28,10 +28,16 @@ Prevent the CPU overutilization when waiting for the process to exit.
 
 Non-code changes:
 * Documentation refactoring and update
-* Introduced the CI flow being hosted on Appveyor. The project page is [here](https://ci.appveyor.com/project/oleg-nenashev/winsw)
+* Introduced the CI flow being hosted on AppVeyor. The project page is [here](https://ci.appveyor.com/project/oleg-nenashev/winsw)
 * Starting from WinSW 2.0, [GitHub](https://github.com/kohsuke/winsw/releases) and NuGet will be the release sources
  * [Maven repository](http://repo.jenkins-ci.org/releases/com/sun/winsw/winsw/) will be periodically updated on-demand
 
+Compatibility notes:
+* WinSW `2.x` is **fully compatible** with WinSW `1.x` in terms of the command-line interface and configuration files.
+* Any behavior difference will be considered as a bug
+* New features like [WinSW extensions](doc/extensions/extensions.md) are disabled by default. 
+They can be enabled via the configuration file.
+
 ##### 1.19.1
 
 Release date: Nov 05, 2016

README.md

@@ -12,11 +12,15 @@ Once you download the installation package, you can rename `winsw.exe` to any na
 See the [project manifest](MANIFEST.md).
 
 ### Download
-Right now the project uses [Jenkins](https://jenkins.io/index.html) Maven repository as a main storage of release files. 
+
+Starting from WinSW `2.x`, the releases are being hosted on [GitHub](https://github.com/kohsuke/winsw/releases) and [nuget.org](https://www.nuget.org/packages/WinSW/).
+
+Due to historical reasons, the project also uses  [Jenkins Maven repository](https://jenkins.io/index.html)  as a secondary source. 
 Binaries are available [here](http://repo.jenkins-ci.org/releases/com/sun/winsw/winsw/). 
 
-Some releases (e.g. alpha- and beta-versions) can be also downloaded from the project's GitHub page. 
+The executables in all sources are [strong-named assemblies](https://msdn.microsoft.com/en-us/library/wd40t7ad%28v=vs.110%29.aspx), which are being singed by randomly generated keys.
-This source of releases is not an **official one**.
+Do not rely on such strong names for security (as well as on other strong names as it recommended by Microsoft). 
+They provide a unique identity only.
 
 ### Usage
 
@@ -30,7 +34,11 @@ Your renamed `winsw.exe` binary also accepts the following commands:
 * `start` to start the service. The service must have already been installed.
 * `stop` to stop the service.
 * `restart` to restart the service. If the service is not currently running, this command acts like `start`.
-* `status` to check the current status of the service. This command prints one line to the console. `NonExistent` to indicate the service is not currently installed, `Started` to indicate the service is currently running, and `Stopped` to indicate that the service is installed but not currently running.
+* `status` to check the current status of the service.
+ * This command prints one line to the console.
+ * `NonExistent` indicates the service is not currently installed
+ * `Started` to indicate the service is currently running
+ * `Stopped` to indicate that the service is installed but not currently running.
 
 ### Supported .NET versions
 
@@ -62,13 +70,16 @@ Naming and download sources for these binaries are currently in flux.
 #### WinSW 2.x
 
 This is a new release line under active development.
-API stability is not guaranteed till the first release, the project structure is in flux.
 
 Major changes since 1.x:
-* Rework of the project structure
+* New executable package targeting the .NET Framework `4.0`. .NET Framework `2.0` is still supported.
-* Better logging
+* Migration of the logging subsystem to `Apache log4net`
-* [Internal extension engine](doc/extensions/extensions.md), which allows extending the WinSW behavior
+* Internal [extension engine](doc/extensions/extensions.md), which allows extending the wrapper's behavior.
-* Executable package targeting the .NET Framework 4.0
+
+See the full changelog in the [release notes](CHANGELOG.md#20).
+
+The version `2.x` is **fully compatible** with the `1.x` configuration file format, 
+  hence the upgrade procedure just requires replacement of the executable file.
 
 #### WinSW 1.x
 

doc/installation.md

@@ -13,7 +13,7 @@ In order to setup WinSW, you commonly need to perform the following steps:
 0. Run `myapp.exe install <OPTIONS>` in order to install the service wrapper.
 0. Optional - Perform additional configuration in the Windows Service Manager.
 0. Optional - Perform extra configurations if required (guidelines are available below).
- * Declare that the executable is compatible with .NET 4 or above
+ * Declare that the executable is compatible with .NET 4 or above (for WinSW 1.x **only**)
  * Enable the WinSW offline mode
 0. Run the service from the Windows Service Manager.
 
@@ -74,7 +74,10 @@ Once the start button is clicked, Windows will start `myapp.exe`,
   
 ### Extra configuration options
   
-#### Making WinSW compatible with .NET runtime 4.0+
+#### Making WinSW 1.x compatible with .NET runtime 4.0+
+
+**NOTE.** _Starting from WinSW `2.0` the release offers a new binary, which targets the .NET Framework 4.0.
+Such configuration is no longer required._  
 
 Modern versions of Windows (e.g. Windows Server 2012 or Windows 10) do not ship with .NET runtime `2.0`, which is what `winsw.exe` is built against. 
 This is because unlike Java, where a newer runtime can host apps developed against earlier runtime, .NET apps need version specific runtimes.