<commit_before>Incompatible changes in ArangoDB 3.4
====================================

It is recommended to check the following list of incompatible changes **before**
upgrading to ArangoDB 3.4, and adjust any client programs if necessary.

The following incompatible changes have been made in ArangoDB 3.4:


Supported platforms
-------------------

The minimum supported architecture for the official release packages of ArangoDB is
now the Nehalem architecture.

All release packages are built with compiler optimizations that require at least
this architecture. The following CPU features are required for running an official
release package (note: these are all included in the Nehalem architecture and upwards):

* SSE2
* SSE3
* SSE4.1
* SSE4.2

In case the target platform does not conform to these requirements, ArangoDB may
not work correctly.

The compiled-in architecture optimizations can be retrieved on most platforms by 
invoking the *arangod* binary with the `--version` option. The optimization switches
will then show up in the output in the line starting with `optimization-flags`, e.g.

```
$ arangod --version
...
optimization-flags: -march=nehalem -msse2 -msse3 -mssse3 -msse4.1 -msse4.2 -mno-sse4a -mno-avx -mno-fma -mno-bmi2 -mno-avx2 -mno-xop -mno-fma4 -mno-avx512f -mno-avx512vl -mno-avx512pf -mno-avx512er -mno-avx512cd -mno-avx512dq -mno-avx512bw -mno-avx512ifma -mno-avx512vbmi
platform: linux
```

Note that to get even more target-specific optimizations, it is possible for end
users to compile ArangoDB on their own with compiler optimizations tailored to the
target environment.


Storage engine
--------------

In ArangoDB 3.4, the default storage engine for new installations is the RocksDB
engine. This differs to previous versions (3.2 and 3.3), in which the default
storage engine was the MMFiles engine.

The MMFiles engine can still be explicitly selected as the storage engine for
all new installations. It's only that the "auto" setting for selecting the storage
engine will now use the RocksDB engine instead of MMFiles engine.

In the following scenarios, the effectively selected storage engine for new
installations will be RocksDB:
<commit_msg>added notes about nscd requirement<commit_after>Incompatible changes in ArangoDB 3.4
====================================

It is recommended to check the following list of incompatible changes **before**
upgrading to ArangoDB 3.4, and adjust any client programs if necessary.

The following incompatible changes have been made in ArangoDB 3.4:


Release packages
----------------

The official ArangoDB release packages for Linux are now built as static executables
linked with the [musl libc](https://www.musl-libc.org/) standard library. For Linux,
there are release packages for the Debian-based family of Linux distributions (.deb), 
and packages for RedHat-based distributions (.rpm). There are no specialized binaries 
for the individual Linux distributions nor for their individual subversions. 

The release packages are intended to be reasonably portable (see minimum supported
architectures below) and should run on a variety of different Linux distributions and
versions.

Release packages are provided for Windows and MacOS as well.


Supported architectures
-----------------------

The minimum supported architecture for the official release packages of ArangoDB is
now the Nehalem architecture.

All release packages are built with compiler optimizations that require at least
this architecture. The following CPU features are required for running an official
release package (note: these are all included in the Nehalem architecture and upwards):

* SSE2
* SSE3
* SSE4.1
* SSE4.2

In case the target platform does not conform to these requirements, ArangoDB may
not work correctly.

The compiled-in architecture optimizations can be retrieved on most platforms by 
invoking the *arangod* binary with the `--version` option. The optimization switches
will then show up in the output in the line starting with `optimization-flags`, e.g.

```
$ arangod --version
...
optimization-flags: -march=nehalem -msse2 -msse3 -mssse3 -msse4.1 -msse4.2 -mno-sse4a -mno-avx -mno-fma -mno-bmi2 -mno-avx2 -mno-xop -mno-fma4 -mno-avx512f -mno-avx512vl -mno-avx512pf -mno-avx512er -mno-avx512cd -mno-avx512dq -mno-avx512bw -mno-avx512ifma -mno-avx512vbmi
platform: linux
```

Note that to get even more target-specific optimizations, it is possible for end
users to compile ArangoDB on their own with compiler optimizations tailored to the
target environment.


Target host requirements
------------------------

When the ArangoDB service is started on a Linux host, it will switch to user 
`arangodb` and group `arangodb` at some point during the startup process.
This user and group are created during ArangoDB package installation as usual. 

However, if either the group `arangodb` or the user `arangodb` cannot be found in
the target hosts local `/etc/group` or `/etc/passwd` storage (for example, 
because system users and groups are stored centrally using NIS, LDAP etc.), then 
the underlying group-lookup implementation used by ArangoDB will always consult 
the local nscd (name-service cache daemon) for this. Effectively this requires
a running nscd instance on hosts that ArangoDB is installed on and that do store
the operating system users in a place other than the host-local `/etc/group` and
`/etc/passwd`.


Storage engine
--------------

In ArangoDB 3.4, the default storage engine for new installations is the RocksDB
engine. This differs to previous versions (3.2 and 3.3), in which the default
storage engine was the MMFiles engine.

The MMFiles engine can still be explicitly selected as the storage engine for
all new installations. It's only that the "auto" setting for selecting the storage
engine will now use the RocksDB engine instead of MMFiles engine.

In the following scenarios, the effectively selected storage engine for new
installations will be RocksDB:

{'fraction_non_alphanumeric': 0.08075572646714596, 'fraction_numerical': 0.018725965557599065, 'mean_word_length': 4.139175257731959, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 1, 'lorem ipsum': 0, 'www.': 1, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4625587', 'n_tokens_mistral': 1701, 'n_tokens_neox': 1597, 'n_words': 806}