diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 072da69b85..8580e8ef39 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ Getting started If you want to help but don't know where to start, here are some low-risk/isolated tasks: -- Merge a [Vim patch]. +- [Merge a Vim patch]. - Try a [complexity:low] issue. - Fix bugs found by [clang scan-build](#clang-scan-build), [coverity](#coverity), and [PVS](#pvs-studio). @@ -23,18 +23,16 @@ Reporting problems - Check the [**FAQ**][wiki-faq]. - Search [existing issues][github-issues] (including closed!) - Update Neovim to the latest version to see if your problem persists. -- If you're using a plugin manager, comment out your plugins, then add them back - in one by one, to narrow down the cause of the issue. -- Crash reports which include a stacktrace are 10x more valuable. -- [Bisecting][git-bisect] to the cause of a regression often leads to an - immediate fix. +- Disable plugins incrementally, to narrow down the cause of the issue. +- When reporting a crash, include a stacktrace. +- [Bisect][git-bisect] to the cause of a regression, if you are able. This is _extremely_ helpful. +- Check `$NVIM_LOG_FILE`, if it exists. Pull requests ("PRs") --------------------- - To avoid duplicate work, create a `[WIP]` pull request as soon as possible. -- Avoid cosmetic changes to unrelated files in the same commit: noise makes - reviews take longer. +- Avoid cosmetic changes to unrelated files in the same commit. - Use a [feature branch][git-feature-branch] instead of the master branch. - Use a **rebase workflow** for small PRs. - After addressing review comments, it's fine to rebase and force-push. @@ -87,10 +85,11 @@ the VCS/git logs more valuable. ### Automated builds (CI) -Each pull request must pass the automated builds ([travis CI] and [quickbuild]). +Each pull request must pass the automated builds on [travis CI], [quickbuild] +and [AppVeyor]. -- CI builds are compiled with [`-Werror`][gcc-warnings], so if your PR - introduces any compiler warnings, the build will fail. +- CI builds are compiled with [`-Werror`][gcc-warnings], so compiler warnings + will fail the build. - If any tests fail, the build will fail. See [Building Neovim#running-tests][wiki-run-tests] to run tests locally. Passing locally doesn't guarantee passing the CI build, because of the @@ -173,6 +172,7 @@ as context, use the `-W` argument as well. [3174]: https://github.com/neovim/neovim/issues/3174 [travis CI]: https://travis-ci.org/neovim/neovim [quickbuild]: http://neovim-qb.szakmeister.net/dashboard -[Vim patch]: https://github.com/neovim/neovim/wiki/Merging-patches-from-upstream-Vim +[AppVeyor]: https://ci.appveyor.com/project/neovim/neovim +[Merge a Vim patch]: https://github.com/neovim/neovim/wiki/Merging-patches-from-upstream-Vim [clang-scan]: https://neovim.io/doc/reports/clang/ [complexity:low]: https://github.com/neovim/neovim/issues?q=is%3Aopen+is%3Aissue+label%3Acomplexity%3Alow diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index 4b3f894cf7..8581bcfb72 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -1366,39 +1366,38 @@ file when reading and include: complete MessagePack object. ============================================================================== -9. Base Directories *base-directories* *xdg* +9. Standard Paths -Nvim conforms to the XDG Base Directory Specification for application -configuration and data file locations. This just means Nvim looks for some -optional settings and uses them if they exist, otherwise defaults are chosen. +Nvim stores configuration and data in standard locations. Plugins are strongly +encouraged to follow this pattern also. + + *base-directories* *xdg* +The "base" (root) directories conform to the XDG Base Directory Specification. https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html +The $XDG_CONFIG_HOME and $XDG_DATA_HOME environment variables are used if they +exist, otherwise default values (listed below) are used. -CONFIGURATION DIRECTORY *$XDG_CONFIG_HOME* +Note: Throughout the user manual these defaults are used as placeholders, e.g. +"~/.config" is understood to mean "$XDG_CONFIG_HOME or ~/.config". - Base directory default: - Unix: ~/.config - Windows: ~/AppData/Local +CONFIG DIRECTORY *$XDG_CONFIG_HOME* + Base Nvim ~ +Unix: ~/.config ~/.config/nvim +Windows: ~/AppData/Local ~/AppData/Local/nvim - Nvim directory: - Unix: ~/.config/nvim/ - Windows: ~/AppData/Local/nvim/ +DATA DIRECTORY *$XDG_DATA_HOME* + Base Nvim ~ +Unix: ~/.local/share ~/.local/share/nvim +Windows: ~/AppData/Local ~/AppData/Local/nvim-data -DATA DIRECTORY *$XDG_DATA_HOME* +STANDARD PATHS *standard-path* - Base directory default: - Unix: ~/.local/share - Windows: ~/AppData/Local - - Nvim directory: - Unix: ~/.local/share/nvim/ - Windows: ~/AppData/Local/nvim-data/ - -Note on Windows the configuration and data directory defaults are the same -(for lack of an alternative), but the sub-directory for data is named -"nvim-data" to separate it from the configuration sub-directory "nvim". - -Throughout other sections of the user manual, the defaults are used as generic -placeholders, e.g. where "~/.config" is mentioned it should be understood to -mean "$XDG_CONFIG_HOME or ~/.config". + *$NVIM_LOG_FILE* +Besides 'debug' and 'verbose', Nvim has a low-level "log of last resort" that +is written directly to the filesystem. This log may also be used by plugins or +RPC clients for debugging. $NVIM_LOG_FILE contains the log file path: > + :echo $NVIM_LOG_FILE +Usually the file is ~/.local/share/nvim/log unless that path is inaccessible +or if $NVIM_LOG_FILE was set before |startup|. vim:tw=78:ts=8:ft=help:norl: