Website integration updates

.Rbuildignore

@@ -2,11 +2,12 @@
 ^doc$
 ^man-roxygen$
 ^Meta$
+^\.Rproj\.user$
 
 ^.*\.Rproj$
-^\.Rproj\.user$
 ^Dockerfile$
 ^docker$
 ^cloudbuild\.yaml$
 ^gke$
+^git-flow$
 ^inst/application/data/taxdata$

NEWS.md

@@ -3,6 +3,7 @@
 * Add directory with GKE instructions and manifests.
 * Upgrade deployed app to R 3.5.3 (from R 3.5.1), improve Docker image with refactored Dockerfile (#91).
 * Removed heavy shinydashboardPlus dependency by using custom collapsible panels (#113).
+* Updated links to the live app and README based on website integration, including GitFlow and release details (#143).
 
 # SmaRP 1.2.0
 

README.md

@@ -1,13 +1,3 @@
-<!--# The Swiss social security system, considered as one of the most robust, is based on a three-pillar regime.
-# The first Pillar, common to most developed countries, is a state-run pay-as-you-earn system with minimum benefits.
-# The voluntary contribution (3rd Pillar) is a privately-run, tax-deductible insurance fund.
-# At the heart of the Swiss system is the so-called Second Pillar, a compulsory, tax-deductible company occupational pension insurance fund.
-# Voluntary additional second Pillar buy-ins are regulated but allow for benefits improvement at retirement age while reducing the tax burden during the working career.
-# The complexity is further increased by a municipality-dependent taxation.
-# Altogether this calls for an early-stage conscious approach towards retirement planning.
-# However, it is not straight-forward to assess effects of elements such as early retirement, moving to a different canton or applying a different voluntary pension schema.
-# SmaRP, Smart Retirement Planning, supports the users in an educated decision-making process.
--->
 
 <img src="inst/application/www/SmaRPSticker.png" align="right" width="15%" height="15%"/>
 
@@ -27,30 +17,43 @@ Unlike other pension calculators, this makes results transparent, comparable, an
 
 ## Using SmaRP
 
-The **SmaRP** Shiny app is deployed to Google Cloud Platform (using [docker
-containers](https://www.docker.com/resources/what-container)) and can be
-accessed at https://mirai-solutions.ch/apps/smarp/.
+The **SmaRP** Shiny app is [deployed](gke#readme) to Google Cloud Platform
+(using [Docker containers](https://www.docker.com/resources/what-container)) and
+can be accessed at https://mirai-solutions.ch/gallery/smarp.
+<!-- TODO: CONSIDER MAKING THE IMAGES PUBLIC
+The corresponding Docker image can also be used to run **SmaRP** in a local
+container
+``` bash
+docker run --rm eu.gcr.io/mirai-sbb/smarp
+```
+-->
 
-The (development version of) **SmaRP** can also be served locally by installing the package from GitHub
+The R package **SmaRP** can be installed from GitHub with
 <!-- argument build_vignettes not available anymore (r-lib/remotes#353), build_opts = "" for a full installation including vignettes  -->
 ``` r
 devtools::install_github("miraisolutions/SmaRP", build_opts = "")
 ```
-and running
+and used to serve the app locally from R via
 ``` r
 SmaRP::launch_application()
 ```
+Since **SmaRP** is developed using a [GitFlow](git-flow#readme) approach, the `master` branch always reflects the _latest_ [release](https://github.com/miraisolutions/SmaRP/releases) of the live app, whereas branch `develop` collects the latest delivered developments for the _next_ releases, which can be installed locally via
+``` r
+devtools::install_github("miraisolutions/SmaRP", "develop", build_opts = "")
+```
+
+Note that **SmaRP** is deployed using [version-stable](https://github.com/rocker-org/rocker-versioned#readme) images from the [Rocker project](https://www.rocker-project.org/). The target environment of live app is currently bound to R 3.5.3. Therefore, the app is developed and tested with the corresponding version of R and packages, as opposed to the latest available versions.
 
 
 ## Details and key features
 
 The evolution of the total retirement fund over time is computed by projecting the value of the occupational fund (2nd Pillar), the private fund (3rd Pillar) and the tax relief, thus deriving their contributions at the desired retirement age.
 
-*Contributions to the second Pillar* are calculated from the salary and any additional voluntary purchases.
+- _Contributions to the second Pillar_ are calculated from the salary and any additional voluntary purchases.
 
-*Contributions to the third Pillar* are fully voluntary and repeated every year until retirement.
+- _Contributions to the third Pillar_ are fully voluntary and repeated every year until retirement.
 
-*Tax savings* are built as an additional fund where tax relieves from a certain year are used as contributions for the next. Tax relieves are calculated using an approximation of the given gross salary and other factors including: residence, civil status, number on kids, etc. 
+- _Tax savings_ are built as an additional fund where tax relieves from a certain year are used as contributions for the next. Tax relieves are calculated using an approximation of the given gross salary and other factors including: residence, civil status, number on kids, etc. 
 
 **Results** of the calculation are available in **SmaRP** in 3 different ways:
 
@@ -72,16 +75,16 @@ The evolution of the total retirement fund over time is computed by projecting t
 
 ### Source code
 
-Core calculations behind this Shiny app have been implemented via several functions, collected in the main source files [SmaRP/R/core.R](https://github.com/miraisolutions/SmaRP/blob/master/R/core.R) and [SmaRP/R/TaxBenefits.R](https://github.com/miraisolutions/SmaRP/blob/master/R/TaxBenefit.R).
+Core calculations behind this Shiny app have been implemented via several functions, collected in the main source files [SmaRP/R/core.R](R/core.R) and [SmaRP/R/TaxBenefits.R](R/TaxBenefit.R).
 
 Documentation for the relevant exported functions used in the app is also provided and can be browsed via
 ``` r
 help(package = "SmaRP")
 ```
-On a functional level, the code is covered by extensive [unit tests](https://github.com/miraisolutions/SmaRP/tree/master/tests/testthat).
+On a functional level, the code is covered by extensive [unit tests](tests/testthat).
 
 
-The source code for the app itself is available under  [SmaRP/inst/application](https://github.com/miraisolutions/SmaRP/blob/master/inst/application).
+The source code for the app itself is available under  [SmaRP/inst/application](inst/application).
 
 
 ### Data sources and references
@@ -91,7 +94,7 @@ An overview of these components can be found at e.g. https://en.wikipedia.org/wi
 A more detailed explanation is available on the Swiss [Federal Social Insurance Office](https://www.bsv.admin.ch/bsv/de/home/sozialversicherungen/ueberblick.html) website (in German).
 
 
-Legal parameters in **SmaRP** are defined in [SmaRP/inst/application/global.R](https://github.com/miraisolutions/SmaRP/blob/master/inst/application/global.R), whereas data is stored under  [SmaRP/inst/application/data](https://github.com/miraisolutions/SmaRP/blob/master/inst/application/data).
+Legal parameters in **SmaRP** are defined in [SmaRP/inst/application/global.R](inst/application/global.R), whereas data is stored under [SmaRP/inst/application/data](inst/application/data).
 
 
 ### Accuracy

git-flow/README.md

@@ -0,0 +1,73 @@
+# GitFlow and Release Model for SmaRP
+
+
+## Branching System
+
+We use a [**GitFlow**](https://nvie.com/posts/a-successful-git-branching-model/) branching model, where the repository holds two main **branches** with an infinite lifetime:
+
+- [**`master`**](https://github.com/miraisolutions/SmaRP/tree/master): reflects the [**latest release**](https://github.com/miraisolutions/SmaRP/releases/latest) to production, i.e. the current version of the [live app](https://mirai-solutions.ch/gallery/smarp).
+- [**`develop`**](https://github.com/miraisolutions/SmaRP/tree/develop): collects all completed developments for the [**next release**](#release).
+
+The overall GitFlow branching system is described as follows
+
+- No work is committed and pushed directly to `master`, which is updated only as part of a [**release**](#release).
+- Small (maintenance) work can be done directly in `develop`, however meaningful pieces should be developed in a dedicated **_feature_ branch** created from `develop` and associated to a GitHub issue. By convention, the branch name is of the form `feature/<ID>-short-title`.
+    - Once completed, the feature branch is merged back into `develop` via a pull request.
+    - Each significant development must be mentioned as a bullet point in the top-section of [**`NEWS.md`**](../NEWS.md) before being pushed to or merged into `develop`, to serve as a change log for the next release.
+- **Hot-fixes** that need to be brought in asap, independently of any other pending development, are carried out in a dedicated branch (of the form `hotfix/<ID>-short-title`) created from `master`. The branch is merged directly back to `master` as a new **patch release**, and must be also merged into `develop` (or possibly an open _release_ branch).
+
+
+## Versioning and Releases {#release}
+
+**SmaRP** uses a [**semantic versioning**](https://semver.org/) scheme bound to the version of the underlying R package. The basic versioning scheme `major.minor.patch` (e.g. `1.1.2`) is reserved for release tagging and the `master` branch (which reflects the most recent release). On the other hand, a fourth _development_ component `-9000` is added for the not-yet-released development happening in the `develop` and _feature_ branches. The package version is updated for the next release (see below) just before the merge into `master` (from `develop` or a _release_ branch). Afterwards, `-9000` is added again to the new version for the future development.
+
+Here we assume that the most recent release is `1.0.0`, hence the version on `develop` is `1.0.0-9000`.
+Releases should only happen from a **stable `develop`**, possibly creating a **_release_ branch** for the release preparation, with a name of the form `release/v<next-release-version>`, e.g. `release/v1.1.0` for a new _minor_ release.
+
+1. **Release preparation**
+    - Consolidate and re-organize the changes in `NEWS.md` (see e.g. Hadley's [recommendations](http://r-pkgs.had.co.nz/release.html#important-files) and [style guide](https://style.tidyverse.org/news.html#news-release)), using the level-3 header `###` for sections if any (nicer rendering in GitHub)
+        - Changes should have been collected in `NEWS.md` already during development
+    - Decide on the **next version** based on whether it is a _patch_, _minor_, _major_ release
+        - For _patch_ changes: `1.0.0-9000` -> `1.0.1` (mainly for hot-fixes)
+        - For _minor_ changes: `1.0.0-9000` -> `1.1.0` (e.g. any change that affects calculations and numbers in the output, minor app refinements or additions, general maintenance)
+        - For _major_ changes: `1.0.0-9000` -> `2.0.0`
+    - Change version number in `NEWS.md` and `DESCRIPTION` files.
+
+(Note: for the remaining steps, a minor release with  `1.1.0` will be used as an example)
+
+2. **Commit and push** all changes with the comment: `1.1.0 release preps` and `closes` lines for all issues mentioned in the `NEWS.md`, e.g.
+
+    ```
+    1.1.0 release preps
+    * closes #26
+    * closes #38
+    ```
+3. Go on GitHub and create a new **pull request** from `develop` (or the _release_ branch) to `master`
+    - Write title in the form "1.1.0 release"
+    - Paste as comment the list of changes in `NEWS.md`
+    - Assign reviewer(s) and set project to SmaRP
+4. As part of the review process, make sure the app can be built and run via Docker locally
+    - Build image with test tag: `docker build -f Dockerfile -t mirai/smarp:test-1.1.0 .`
+    - Run the app: `docker run --rm -p 80:80 mirai/smarp:test-1.1.0`
+    - Visit `http://127.0.0.1:80` and test the app
+    - Type `Ctrl+C` to stop the container, which is automatically removed (`--rm`)
+    - Cleanup the image: `docker image rm mirai/smarp:test-1.1.0` 
+5. Once the pull request is merged into `master`, create a **new release on GitHub** ([Code > releases > Draft new release](https://github.com/miraisolutions/SmaRP/releases/new))
+    - Tag version: v1.1.0
+    - Title: SmaRP 1.1.0
+    - Body: Paste as comment the list of changes in `NEWS.md`
+    - Click on "Publish release"
+6. If the release was done from a _release_ branch, a pull request should be created to merge it back into `develop`
+7. Prepare for **next version** on `develop`
+    - Change the `Version` field in `DESCRIPTION` to the development version `1.1.0-9000`
+    - Create a new heading in `NEWS.md` for `SmaRP 1.1.0-9000`
+    - Commit and push
+
+
+## References
+
+* [GitFlow for GitHub](https://datasift.github.io/gitflow) by DataSift.
+* [Git and GitHub](http://r-pkgs.had.co.nz/git.html) from Hadley Wickham's [R packages](http://r-pkgs.had.co.nz/).
+* [Package versioning](http://r-pkgs.had.co.nz/description.html#version) from Hadley Wickham's [R packages](http://r-pkgs.had.co.nz/).
+* [Releasing a package](http://r-pkgs.had.co.nz/release.html) from Hadley Wickham's [R packages](http://r-pkgs.had.co.nz/).
+

inst/application/report.Rmd

@@ -105,7 +105,7 @@ Kinder <- format(round(params$Kinder, 2), nsmall = 0)
 
 Smart Retirement Planning (**SmaRP**) is a [Mirai Solutions](https://mirai-solutions.ch/) initiative designed to guide people working in Switzerland towards a strategic decision-making process for their retirement.
 
-It is implemented as an [R Shiny](https://shiny.rstudio.com/) pension calculator web app, in the form of an R package. The source code is available on [GitHub](https://github.com/miraisolutions/SmaRP.git) and the app itself online at http://mirai-solutions.ch/apps/smarp/.
+It is implemented as an [R Shiny](https://shiny.rstudio.com/) pension calculator web app, in the form of an R package. The source code is available on [GitHub](https://github.com/miraisolutions/SmaRP.git) and the app itself online at https://mirai-solutions.ch/gallery/smarp.
 
 **SmaRP** is based on the [three pillars pension system](https://en.wikipedia.org/wiki/Pension_system_in_Switzerland) and reflects the complexity of its legal framework. The bulk of the retirement income are the second and third pillar, which employees can actively manage and make decisions impacting their total pension fund at retirement. The first pillar is not considered as it is a pay-as-you-go universal system whose benefits depend on the income earned during the working life and the number of years contributed. In addition, since non-mandatory contributions are tax favored, SmaRP incorporates an additional fund -the Tax benefits- to outline the effects of those tax reliefs on the long run.