Created upgrade doc explaining how to upgrade from Shlinnk 1.x to 2.x

CHANGELOG.md

@@ -27,7 +27,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com), and this
     * Preview generation feature completely removed.
     * Authentication against REST API using JWT is no longer supported.
 
-    See [UPGRADING doc](UPGRADING.md) in order to get details on how to migrate to this version.
+    See [UPGRADE doc](UPGRADE.md) in order to get details on how to migrate to this version.
 
 #### Fixed
 

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016-2019 Alejandro Celaya
+Copyright (c) 2016-2020 Alejandro Celaya
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -9,6 +9,8 @@
 
 A PHP-based self-hosted URL shortener that can be used to serve shortened URLs under your own custom domain.
 
+> This document references Shlink 2.x. If you are using an older version and want to upgrade, follow the [UPGRADE](UPGRADE.md) doc.
+
 ## Table of Contents
 
 - [Installation](#installation)
@@ -197,25 +199,11 @@ Finally access to [https://app.shlink.io](https://app.shlink.io) and configure y
 
 ### Bonus
 
-Depending on the shlink version you installed and how you serve it, there are a couple of time-consuming tasks that shlink expects you to do manually, or at least it is recommended, since it will improve runtime performance.
+Geo-locating visits to your short links is a time-consuming task. When serving Shlink with swoole, the geo-location task is automatically run asynchronously just after a visit to a short URL happens.
 
-Those tasks can be performed using shlink's CLI tool, so it should be easy to schedule them to be run in the background (for example, using cron jobs):
+However, if you are not serving Shlink with swoole, you will have to schedule the geo-location task to be run regularly in the background (for example, using cron jobs):
 
-* **For shlink older than 1.18.0 or not using swoole to serve it**: Resolve IP address locations: `/path/to/shlink/bin/cli visit:locate`
+The command you need to run is `/path/to/shlink/bin/cli visit:locate`, and you can optionally provide the `-q` flag to remove any output and avoid your cron logs to be polluted.
-
-    If you don't run this command regularly, the stats will say all visits come from *unknown* locations.
-
-    > If you serve Shlink with swoole and use v1.18.0 at least, visit location is automatically scheduled by Shlink just after the visit occurs, using swoole's task system.
-
-* **For shlink older than v1.17.0**: Update IP geolocation database: `/path/to/shlink/bin/cli visit:update-db`
-
-    When shlink is installed it downloads a fresh [GeoLite2](https://dev.maxmind.com/geoip/geoip2/geolite2/) db file. Running this command will update this file.
-
-    The file is updated the first Tuesday of every month, so it should be enough running this command the first Wednesday.
-
-    > You don't need this if you use Shlink v1.17.0 or newer, since now it downloads/updates the geolocation database automatically just before trying to use it.
-
-*Any of these commands accept the `-q` flag, which makes it not display any output. This is recommended when configuring the commands as cron jobs.*
 
 ## Update to new version
 

UPGRADE.md

@@ -0,0 +1,62 @@
+# Upgrading
+
+## From v1.x to v2.x
+
+### Preview generation
+
+The ability to generate website previews has been completely removed and has no replacement.
+
+The feature never properly worked, and it wasn't really useful. Because of that, the feature is no longer available on Shlink 2.x
+
+Removing this feature has these implications:
+
+* The `short-url:process-previews` CLI command no longer exists, and an error will be thrown if executed.
+* The `/{shortCode}/preview` path is no longer valid, and will return a 404 status.
+
+### Removed paths
+
+These routes have been removed, but have a direct replacement:
+
+* `/qr/{shortCode}[/{size}]` -> `/{shortCode}/qr-code[/{size}]`
+* `PUT /rest/v{version}/short-urls/{shortCode}` -> `PATCH /rest/v{version}/short-urls/{shortCode}`
+
+When using the old ones, a 404 status will me returned now.
+
+### Removed command and route aliases
+
+All the aliases for the CLI commands in the `short-urls` namespace have been removed. If you were using any of those commands with the `shortcode` or `short-code` prefixes, make sure to update them to use the `short-urls` prefix instead.
+
+The same happens for all REST endpoints starting with `/short-code`. They were previously aliased to `/short-urls` ones, but they will return a 404 now. Make sure to update them accordingly.
+
+### JWT authentication removed
+
+Shlink's REST API no longer accepts authentication using a JWT token. The API key has to be passed now in the `x-api-key` header.
+
+Removing this feature has these implications:
+
+* Shlink will no longer introspect the `Authorization` header for Bearer tokens.
+* The `POST /rest/v{version}/authenticate` endpoint no longer exists and will return a 404.
+
+### API version is now required
+
+Endpoints need to provide a version in the path now. Previously, not providing a version used to fall back to v1. Now, it will return a 404 status, as no route will match.
+
+The only exception is the `/rest/health` endpoint, which will continue working without the version.
+
+### Changes in models
+
+The next REST API models have changed:
+
+* **ShortUrl**: The `originalUrl` property was deprecated and has been removed. Use `longUrl` instead.
+* **Visit**: The `remoteAddr` property was deprecated and has been removed. It has no replacement.
+* **VisitLocation**: The `latitude` and `longitude` properties are no longer strings, but float.
+
+### URL validation
+
+Shlink can verify provided long URLs are valid before trying to shorten them. Starting with v2, it no longer does it by default and needs to be explicitly enabled instead of explicitly disabled.
+
+### Removed config options
+
+The `not_found_redirect_to` config option and the `NOT_FOUND_REDIRECT_TO` env var are no longer taken into consideration for the docker image.
+
+Instead, use `invalid_short_url_redirect_to` and `INVALID_SHORT_URL_REDIRECT_TO` respectively.