BREAKING CHANGES: Migrate from io.github.soc to dev.dirs, ...

... change behavior of `configDir` on macOS, release version 20.

README.md

@@ -1,5 +1,5 @@
-[![Maven Central](https://img.shields.io/maven-central/v/io.github.soc/directories.svg)](https://search.maven.org/#search|gav|1|g%3A%22io.github.soc%22%20AND%20a%3A%22directories%22)
-[![API documentation](http://javadoc.io/badge/io.github.soc/directories.svg)](http://javadoc.io/doc/io.github.soc/directories)
+[![Maven Central](https://img.shields.io/maven-central/v/dev.dirs/directories.svg)](https://search.maven.org/#search|gav|1|g%3A%22dev.dirs%22%20AND%20a%3A%22directories%22)
+[![API documentation](http://javadoc.io/badge/dev.dirs/directories.svg)](http://javadoc.io/doc/dev.dirs/directories)
 ![actively developed](https://img.shields.io/badge/maintenance-actively--developed-brightgreen.svg)
 [![TravisCI status](https://img.shields.io/travis/dirs-dev/directories-jvm/master.svg?label=Linux%20build)](https://travis-ci.org/dirs-dev/directories-jvm)
 [![AppVeyor status](https://img.shields.io/appveyor/ci/soc/directories-jvm/master.svg?label=Windows%20build)](https://ci.appveyor.com/project/soc/directories-jvm/branch/master)
@@ -25,7 +25,7 @@ The library provides the location of these directories by leveraging the mechani
 
 This library is written in Java, and runs on the JVM (≥ 6).
 
-A version of this library implemented in Rust is provided by [directories-rs](https://github.com/soc/directories-rs).
+A version of this library implemented in Rust is provided by [directories-rs](https://github.com/dirs-dev/directories-rs).
 
 ## Usage
 
@@ -36,19 +36,19 @@ Add the library as a dependency to your project:
 ##### Maven
 ```xml
 <dependency>
-  <groupId>io.github.soc</groupId>
+  <groupId>dev.dirs</groupId>
   <artifactId>directories</artifactId>
-  <version>12</version>
+  <version>20</version>
 </dependency>
 ```
 ##### Gradle
 ```groovy
-compile 'io.github.soc:directories:12'
+compile 'dev.dirs:directories:20'
 ```
 
 ##### SBT
 ```scala
-"io.github.soc" % "directories" % "12"
+"dev.dirs" % "directories" % "20"
 ```
 
 The library itself is built against Java 6 to allow for the widest possible usage scenarios.
@@ -59,9 +59,9 @@ It can be used on any Java version >= 6.
 Library run by user Alice:
 
 ```java
-import io.github.soc.directories.ProjectDirectories;
-import io.github.soc.directories.BaseDirectories;
-import io.github.soc.directories.UserDirectories;
+import dev.dirs.ProjectDirectories;
+import dev.dirs.BaseDirectories;
+import dev.dirs.UserDirectories;
 
 ProjectDirectories myProjDirs = ProjectDirectories.from("com", "Foo Corp", "Bar App");
 myProjDirs.configDir;
@@ -114,14 +114,15 @@ that have been defined according to the conventions of the operating system the
 
 If you want to compute the location of cache, config or data folders for your own application or project, use `ProjectDirectories` instead.
 
-| Field name      | Value on Linux / BSD                                             | Value on Windows                  | Value on macOS                      |
+| Field name      | Value on Linux / BSD / Solaris                                   | Value on Windows                  | Value on macOS                      |
 | --------------- | ---------------------------------------------------------------- | --------------------------------- | ----------------------------------- |
 | `homeDir`       | `$HOME`                                                          | `{FOLDERID_UserProfile}`          | `$HOME`                             |
 | `cacheDir`      | `$XDG_CACHE_HOME`  or `$HOME`/.cache                             | `{FOLDERID_LocalApplicationData}` | `$HOME`/Library/Caches              |
-| `configDir`     | `$XDG_CONFIG_HOME` or `$HOME`/.config                            | `{FOLDERID_ApplicationData}`      | `$HOME`/Library/Preferences         |
+| `configDir`     | `$XDG_CONFIG_HOME` or `$HOME`/.config                            | `{FOLDERID_ApplicationData}`      | `$HOME`/Library/Application Support |
 | `dataDir`       | `$XDG_DATA_HOME`   or `$HOME`/.local/share                       | `{FOLDERID_ApplicationData}`      | `$HOME`/Library/Application Support |
 | `dataLocalDir`  | `$XDG_DATA_HOME`   or `$HOME`/.local/share                       | `{FOLDERID_LocalApplicationData}` | `$HOME`/Library/Application Support |
 | `executableDir` | `$XDG_BIN_HOME` or `$XDG_DATA_HOME`/../bin or `$HOME`/.local/bin | `null`                            | `null`                              |
+| `preferencesDir`| `$XDG_CONFIG_HOME` or `$HOME`/.config                            | `{FOLDERID_ApplicationData}`      | `$HOME`/Library/Preferences         |
 | `runtimeDir`    | `$XDG_RUNTIME_DIR` or `null`                                     | `null`                            | `null`                              |
 
 ### `UserDirectories`
@@ -147,13 +148,14 @@ that have been defined according to the conventions of the operating system the
 The intended use-case for `ProjectDirectories` is to compute the location of cache, config or data folders for your own application or project,
 which are derived from the standard directories.
 
-| Field name     | Value on Linux / BSD                                                       | Value on Windows                                         | Value on macOS                                       |
-| -------------- | -------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------- |
-| `cacheDir`     | `$XDG_CACHE_HOME`/`<project_path>` or `$HOME`/.cache/`<project_path>`      | `{FOLDERID_LocalApplicationData}`/`<project_path>`/cache | `$HOME`/Library/Caches/`<project_path>`              |
-| `configDir`    | `$XDG_CONFIG_HOME`/`<project_path>`  or `$HOME`/.config/`<project_path>`   | `{FOLDERID_ApplicationData}`/`<project_path>`/config     | `$HOME`/Library/Preferences/`<project_path>`         |
-| `dataDir`      | `$XDG_DATA_HOME`/`<project_path>` or `$HOME`/.local/share/`<project_path>` | `{FOLDERID_ApplicationData}`/`<project_path>`/data       | `$HOME`/Library/Application Support/`<project_path>` |
-| `dataLocalDir` | `$XDG_DATA_HOME`/`<project_path>` or `$HOME`/.local/share/`<project_path>` | `{FOLDERID_LocalApplicationData}`/`<project_path>`/data  | `$HOME`/Library/Application Support/`<project_path>` |
-| `runtimeDir`   | `$XDG_RUNTIME_DIR`/`<project_path>`                                        | `null`                                                   | `null`                                               |
+| Field name      | Value on Linux / BSD                                                       | Value on Windows                                         | Value on macOS                                       |
+| --------------- | -------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------- |
+| `cacheDir`      | `$XDG_CACHE_HOME`/`<project_path>` or `$HOME`/.cache/`<project_path>`      | `{FOLDERID_LocalApplicationData}`/`<project_path>`/cache | `$HOME`/Library/Caches/`<project_path>`              |
+| `configDir`     | `$XDG_CONFIG_HOME`/`<project_path>`  or `$HOME`/.config/`<project_path>`   | `{FOLDERID_ApplicationData}`/`<project_path>`/config     | `$HOME`/Library/Application Support/`<project_path>` |
+| `dataDir`       | `$XDG_DATA_HOME`/`<project_path>` or `$HOME`/.local/share/`<project_path>` | `{FOLDERID_ApplicationData}`/`<project_path>`/data       | `$HOME`/Library/Application Support/`<project_path>` |
+| `dataLocalDir`  | `$XDG_DATA_HOME`/`<project_path>` or `$HOME`/.local/share/`<project_path>` | `{FOLDERID_LocalApplicationData}`/`<project_path>`/data  | `$HOME`/Library/Application Support/`<project_path>` |
+| `preferencesDir`| `$XDG_CONFIG_HOME`/`<project_path>`  or `$HOME`/.config/`<project_path>`   | `{FOLDERID_ApplicationData}`/`<project_path>`/config     | `$HOME`/Library/Preferences/`<project_path>`         |
+| `runtimeDir`    | `$XDG_RUNTIME_DIR`/`<project_path>`                                        | `null`                                                   | `null`                                               |
 
 The specific value of `<project_path>` is computed by the
 
@@ -185,7 +187,21 @@ The version number of this library consists of a whole number, which is incremen
 
 ## Changelog
 
-### 12 – current stable version
+### 20 – current stable `dev.dirs:directories` release
+
+- **BREAKING CHANGE** The behavior of `configDir` on macOS has been adjusted:
+  - The existing `BaseDirectories#configDir` has been changed to return the `Application Support` directory, as suggested by Apple documentation.
+  - The newly added `BaseDirectories#preferencesDir` returns the `Preferences` directory now,
+    which – according to Apple documentation – shall only be used to store .plist files.
+  - The behavior of `configDir` on non macOS platforms has not been changed.
+  – `preferencesDir` is the same `configDir` on non macOS platforms.
+  - The behavior of `ProjectDirectories` has been adjusted accordingly.
+  - If you have used `BaseDirectories#configDir` or `ProjectDirectories#configDir` to store files,
+    it may be necessary to write code that migrates the files to the new location.
+
+### 19-13 – Reserved for bug fixes on `soc.github.io:directories`
+
+### 12 – current stable `soc.github.io:directories` release
 
 - Adjust library to deal with breaking changes in Java caused by CVE-2019-2958 (see JDK-8221858). Thanks @alexarchambault!
 - Support Solaris. Thanks @tomasjura!

build.sbt

@@ -1,11 +1,11 @@
 lazy val root = (project in file("."))
   .settings(
     name                 := "directories",
-    organization         := "io.github.soc",
+    organization         := "dev.dirs",
     managedScalaInstance := false,
     crossPaths           := false,
-    version              := "12",
-    homepage             := Some(url("https://github.com/soc/directories-jvm")),
+    version              := "20",
+    homepage             := Some(url("https://github.com/dirs-dev/directories-jvm")),
     licenses             := Seq("Mozilla Public License 2.0" -> url("https://opensource.org/licenses/MPL-2.0")),
     fork                 := true,
     // The javaHome setting can be removed if building against the latest installed version of Java is acceptable.
@@ -25,14 +25,14 @@ lazy val root = (project in file("."))
     packageOptions in (Compile, packageBin) += {
       import java.util.jar.{Attributes, Manifest}
       val manifest = new Manifest
-      manifest.getMainAttributes.put(new Attributes.Name("Automatic-Module-Name"), "io.github.soc.directories")
+      manifest.getMainAttributes.put(new Attributes.Name("Automatic-Module-Name"), "dev.dirs.directories")
       Package.JarManifest(manifest)
     },
     pomIncludeRepository := { _ => false },
     pomExtra             :=
       <scm>
-        <url>git@github.com:soc/directories-jvm.git</url>
-        <connection>scm:git:git@github.com:soc/directories-jvm.git</connection>
+        <url>git@github.com:dirs-dev/directories-jvm.git</url>
+        <connection>scm:git:git@github.com:dirs-dev/directories-jvm.git</connection>
       </scm>
       <developers>
         <developer>

src/main/java/io/github/soc/directories/BaseDirectories.java → src/main/java/dev/dirs/BaseDirectories.java

@@ -1,6 +1,6 @@
-package io.github.soc.directories;
+package dev.dirs;
 
-import static io.github.soc.directories.Util.*;
+import static dev.dirs.Util.*;
 
 /** {@code BaseDirectories} provides paths of user-invisible standard directories, following the conventions of the operating system the library is running on.
   * <p>
@@ -73,7 +73,7 @@ public final class BaseDirectories {
     */
   public final String cacheDir;
 
-  /** Returns the path to the user's config directory.
+  /** Returns the path to the user's configuration directory.
     * <br><br>
     * <table border="1" cellpadding="1" cellspacing="0">
     * <tr>
@@ -88,8 +88,8 @@ public final class BaseDirectories {
     * </tr>
     * <tr>
     * <td>macOS</td>
-    * <td>{@code $HOME}/Library/Preferences</td>
-    * <td>/Users/Alice/Library/Preferences</td>
+    * <td>{@code $HOME}/Library/Application Support</td>
+    * <td>/Users/Alice/Library/Application Support</td>
     * </tr>
     * <tr>
     * <td>Windows</td>
@@ -181,6 +181,33 @@ public final class BaseDirectories {
     */
   public final String executableDir;
 
+  /** Returns the path to the user's preferences directory.
+   * <br><br>
+   * <table border="1" cellpadding="1" cellspacing="0">
+   * <tr>
+   * <th align="left">Platform</th>
+   * <th align="left">Value</th>
+   * <th align="left">Example</th>
+   * </tr>
+   * <tr>
+   * <td>Linux/BSD</td>
+   * <td>{@code $XDG_CONFIG_HOME} or {@code $HOME}/.config</td>
+   * <td>/home/alice/.config</td>
+   * </tr>
+   * <tr>
+   * <td>macOS</td>
+   * <td>{@code $HOME}/Library/Preferences</td>
+   * <td>/Users/Alice/Library/Preferences</td>
+   * </tr>
+   * <tr>
+   * <td>Windows</td>
+   * <td>{@code {FOLDERID_RoamingAppData}}</td>
+   * <td>C:\Users\Alice\AppData\Roaming</td>
+   * </tr>
+   * </table>
+   */
+  public final String preferencesDir;
+
   /** Returns the path to the user's runtime directory.
     * <br><br>
     * <table border="1" cellpadding="1" cellspacing="0">
@@ -224,32 +251,35 @@ private BaseDirectories() {
       case LIN:
       case BSD:
       case SOLARIS:
-        homeDir       = System.getProperty("user.home");
-        cacheDir      = defaultIfNullOrEmpty(System.getenv("XDG_CACHE_HOME"),  homeDir, "/.cache");
-        configDir     = defaultIfNullOrEmpty(System.getenv("XDG_CONFIG_HOME"), homeDir, "/.config");
-        dataDir       = defaultIfNullOrEmpty(System.getenv("XDG_DATA_HOME"),   homeDir, "/.local/share");
-        dataLocalDir  = dataDir;
-        executableDir = linuxExecutableDir(homeDir, dataDir);
-        runtimeDir    = linuxRuntimeDir(null);
+        homeDir        = System.getProperty("user.home");
+        cacheDir       = defaultIfNullOrEmpty(System.getenv("XDG_CACHE_HOME"),  homeDir, "/.cache");
+        configDir      = defaultIfNullOrEmpty(System.getenv("XDG_CONFIG_HOME"), homeDir, "/.config");
+        dataDir        = defaultIfNullOrEmpty(System.getenv("XDG_DATA_HOME"),   homeDir, "/.local/share");
+        dataLocalDir   = dataDir;
+        executableDir  = linuxExecutableDir(homeDir, dataDir);
+        preferencesDir = configDir;
+        runtimeDir     = linuxRuntimeDir(null);
         break;
       case MAC:
-        homeDir       = System.getProperty("user.home");
-        cacheDir      = homeDir + "/Library/Caches/";
-        configDir     = homeDir + "/Library/Preferences/";
-        dataDir       = homeDir + "/Library/Application Support/";
-        dataLocalDir  = dataDir;
-        executableDir = null;
-        runtimeDir    = null;
+        homeDir        = System.getProperty("user.home");
+        cacheDir       = homeDir + "/Library/Caches/";
+        configDir      = homeDir + "/Library/Application Support/";
+        dataDir        = configDir;
+        dataLocalDir   = configDir;
+        executableDir  = null;
+        preferencesDir = homeDir + "/Library/Preferences/";
+        runtimeDir     = null;
         break;
       case WIN:
         String[] winDirs = getWinDirs("5E6C858F-0E22-4760-9AFE-EA3317B67173", "3EB685DB-65F9-4CF6-A03A-E3EF65729F3D", "F1B32785-6FBA-4FCF-9D55-7B8E7F157091");
-        homeDir       = winDirs[0];
-        dataDir       = winDirs[1];
-        dataLocalDir  = winDirs[2];
-        configDir     = dataDir;
-        cacheDir      = dataLocalDir;
-        executableDir = null;
-        runtimeDir    = null;
+        homeDir        = winDirs[0];
+        dataDir        = winDirs[1];
+        dataLocalDir   = winDirs[2];
+        configDir      = dataDir;
+        cacheDir       = dataLocalDir;
+        executableDir  = null;
+        preferencesDir = configDir;
+        runtimeDir     = null;
         break;
       default:
         throw new UnsupportedOperatingSystemException("Base directories are not supported on " + operatingSystemName);
@@ -259,13 +289,14 @@ private BaseDirectories() {
   @Override
   public String toString() {
     return "BaseDirectories (" + operatingSystemName + "):\n" +
-        "  homeDir       = '" + homeDir       + "'\n" +
-        "  cacheDir      = '" + cacheDir      + "'\n" +
-        "  configDir     = '" + configDir     + "'\n" +
-        "  dataDir       = '" + dataDir       + "'\n" +
-        "  dataLocalDir  = '" + dataLocalDir  + "'\n" +
-        "  executableDir = '" + executableDir + "'\n" +
-        "  runtimeDir    = '" + runtimeDir    + "'\n";
+        "  homeDir        = '" + homeDir        + "'\n" +
+        "  cacheDir       = '" + cacheDir       + "'\n" +
+        "  configDir      = '" + configDir      + "'\n" +
+        "  dataDir        = '" + dataDir        + "'\n" +
+        "  dataLocalDir   = '" + dataLocalDir   + "'\n" +
+        "  executableDir  = '" + executableDir  + "'\n" +
+        "  preferencesDir = '" + preferencesDir + "'\n" +
+        "  runtimeDir     = '" + runtimeDir     + "'\n";
   }
 
   @Override
@@ -275,33 +306,36 @@ public boolean equals(Object o) {
 
     BaseDirectories that = (BaseDirectories) o;
 
-    if (homeDir       != null ? !homeDir      .equals(that.homeDir)       : that.homeDir       != null)
+    if (homeDir       != null ? !homeDir        .equals(that.homeDir)        : that.homeDir        != null)
+      return false;
+    if (cacheDir       != null ? !cacheDir      .equals(that.cacheDir)       : that.cacheDir       != null)
       return false;
-    if (cacheDir      != null ? !cacheDir     .equals(that.cacheDir)      : that.cacheDir      != null)
+    if (configDir      != null ? !configDir     .equals(that.configDir)      : that.configDir      != null)
       return false;
-    if (configDir     != null ? !configDir    .equals(that.configDir)     : that.configDir     != null)
+    if (dataDir        != null ? !dataDir       .equals(that.dataDir)        : that.dataDir        != null)
       return false;
-    if (dataDir       != null ? !dataDir      .equals(that.dataDir)       : that.dataDir       != null)
+    if (dataLocalDir   != null ? !dataLocalDir  .equals(that.dataLocalDir)   : that.dataLocalDir   != null)
       return false;
-    if (dataLocalDir  != null ? !dataLocalDir .equals(that.dataLocalDir)  : that.dataLocalDir  != null)
+    if (executableDir  != null ? !executableDir .equals(that.executableDir)  : that.executableDir  != null)
       return false;
-    if (executableDir != null ? !executableDir.equals(that.executableDir) : that.executableDir != null)
+    if (preferencesDir != null ? !preferencesDir.equals(that.preferencesDir) : that.preferencesDir != null)
       return false;
-    if (runtimeDir    != null ? !runtimeDir   .equals(that.runtimeDir)    : that.runtimeDir    != null)
+    if (runtimeDir     != null ? !runtimeDir    .equals(that.runtimeDir)     : that.runtimeDir     != null)
       return false;
     return true;
   }
 
   @Override
   public int hashCode() {
     int result = 0;
-    result = 31 * result + (homeDir       != null ? homeDir      .hashCode() : 0);
-    result = 31 * result + (cacheDir      != null ? cacheDir     .hashCode() : 0);
-    result = 31 * result + (configDir     != null ? configDir    .hashCode() : 0);
-    result = 31 * result + (dataDir       != null ? dataDir      .hashCode() : 0);
-    result = 31 * result + (dataLocalDir  != null ? dataLocalDir .hashCode() : 0);
-    result = 31 * result + (executableDir != null ? executableDir.hashCode() : 0);
-    result = 31 * result + (runtimeDir    != null ? runtimeDir   .hashCode() : 0);
+    result = 31 * result + (homeDir        != null ? homeDir       .hashCode() : 0);
+    result = 31 * result + (cacheDir       != null ? cacheDir      .hashCode() : 0);
+    result = 31 * result + (configDir      != null ? configDir     .hashCode() : 0);
+    result = 31 * result + (dataDir        != null ? dataDir       .hashCode() : 0);
+    result = 31 * result + (dataLocalDir   != null ? dataLocalDir  .hashCode() : 0);
+    result = 31 * result + (executableDir  != null ? executableDir .hashCode() : 0);
+    result = 31 * result + (preferencesDir != null ? preferencesDir.hashCode() : 0);
+    result = 31 * result + (runtimeDir     != null ? runtimeDir    .hashCode() : 0);
     return result;
   }
 }