docs: final update after rewrite

Make clear this is not the default branch

1 files changed, 25 insertions, 22 deletions

diff --git a/README.md b/README.md
index 703a41781..ef3a9f32c 100644
--- a/README.md
+++ b/README.md
@@ -1,30 +1,17 @@
 <h1 align="center">
   <img src="https://github.com/nvim-treesitter/nvim-treesitter/assets/2361214/0513b223-c902-4f12-92ee-8ac4d8d6f41f" alt="nvim-treesitter">
 </h1>
-<div align="center">
-  <p>
-    <a href="https://matrix.to/#/#nvim-treesitter:matrix.org">
-      <img alt="Matrix Chat" src="https://img.shields.io/matrix/nvim-treesitter:matrix.org" />
-    </a>
-    <a href="https://github.com/nvim-treesitter/nvim-treesitter/actions?query=workflow%3A%22Linting+and+style+checking%22+branch%3Amaster">
-      <img alt="Linting and Style" src="https://github.com/nvim-treesitter/nvim-treesitter/workflows/Linting%20and%20style%20checking/badge.svg" />
-    </a>
-    <a href="https://github.com/nvim-treesitter/nvim-treesitter/actions?query=workflow%3A%22Check+loading+of+syntax+files%22+branch%3Amaster">
-      <img alt="Syntax files" src="https://github.com/nvim-treesitter/nvim-treesitter/workflows/Check%20loading%20of%20syntax%20files/badge.svg" />
-    </a>
-  </p>
-</div>
-
-
->[!WARNING]
-> This branch is a [full, incompatible, rewrite of `nvim-treesitter`](https://github.com/nvim-treesitter/nvim-treesitter/issues/4767) and [work in progress](TODO.md). The **stable** branch is [`master`](https://github.com/nvim-treesitter/nvim-treesitter/tree/master).
 
 The `nvim-treesitter` plugin provides
 1. functions for installing, updating, and removing [**tree-sitter parsers**](SUPPORTED_LANGUAGES.md);
-2. a collection of **queries** for enabling tree-sitter features built into Neovim for these languages.
+2. a collection of **queries** for enabling tree-sitter features built into Neovim for these languages;
+3. a staging ground for [treesitter-based features](#Supported-features) considered for upstreaming to Neovim.
 
 For details on these and how to help improving them, see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
+>[!CAUTION]
+> This is a full, incompatible, rewrite. If you can't or don't want to update, check out the [`master` branch](https://github.com/nvim-treesitter/nvim-treesitter/blob/master/README.md) (which is locked but will remain available for backward compatibility).
+
 # Quickstart
 
 ## Requirements
@@ -35,6 +22,12 @@ For details on these and how to help improving them, see [CONTRIBUTING.md](./CON
 - a C compiler in your path (see <https://docs.rs/cc/latest/cc/#compile-time-requirements>)
 - `Node` (23.0.0 or later) for some parsers (see the [list of supported languages](SUPPORTED_LANGUAGES.md))
 
+>[!IMPORTANT]
+> The **support policy** for Neovim is
+> 1. the _latest_ [stable release](https://github.com/neovim/neovim/releases/tag/stable);
+> 2. the _latest_ [nightly prerelease](https://github.com/neovim/neovim/releases/tag/nightly).
+> Other versions may work but are neither tested nor considered for fixes. In general, compatibility with Nvim 0.X is removed after the release of Nvim 0.(X+1).1.
+
 ## Installation
 
 You can install `nvim-treesitter` with your favorite package manager (or using the native `package` feature of vim, see `:h packages`).
@@ -43,14 +36,20 @@ This plugin is only guaranteed to work with specific versions of language parser
 It is strongly recommended to automate this; e.g., using [lazy.nvim](https://github.com/folke/lazy.nvim)
 
 ```lua
-require('lazy').setup(
-  { 'nvim-treesitter/nvim-treesitter', build = ':TSUpdate', lazy = false }
-)
+require('lazy').setup({
+  'nvim-treesitter/nvim-treesitter',
+  lazy = false,
+  branch = 'main',
+  build = ':TSUpdate'
+})
 ```
 
 >[!IMPORTANT]
 > This plugin does not support lazy-loading.
 
+>[!IMPORTANT]
+> Make sure to specify the `main` branch since (for now) the default branch is [`master`](https://github.com/nvim-treesitter/nvim-treesitter/blob/master/README.md).
+
 ## Setup
 
 `nvim-treesitter` can be configured by calling `setup`. The following snippet lists the available options and their default values. **You do not need to call `setup` for `nvim-treesitter` to work using default values.**
@@ -69,6 +68,7 @@ require'nvim-treesitter'.install { 'rust', 'javascript', 'zig' }
 ```
 
 (This is a no-op if the parsers are already installed.) Note that this function runs asynchronously; for synchronous installation in a script context ("bootstrapping"), you need to `wait()` for it to finish:
+
 ```lua
 require('nvim-treesitter').install({ 'rust', 'javascript', 'zig' }):wait(300000) -- wait max. 5 minutes
 ```
@@ -143,13 +143,14 @@ callback = function()
       branch = 'develop', -- only needed if different from default branch
       location = 'parser', -- only needed if the parser is in subdirectory of a "monorepo"
       generate = true, -- only needed if repo does not contain pre-generated `src/parser.c`
-      generate_from_json = false, -- only needed if repo does not contain `src/grammar.json`
+      generate_from_json = false, -- only needed if repo does not contain `src/grammar.json` either
     },
   }
 end})
 ```
 
 Alternatively, if you have a local checkout, you can instead use
+
 ```lua
     install_info = {
       path = '~/parsers/tree-sitter-zimbu',
@@ -177,6 +178,7 @@ If Neovim does not detect your language's filetype by default, you can use [Neov
 ### Modifying parsers
 
 You can use the same approach for overriding parser information. E.g., if you always want to generate the `lua` parser from grammar, add
+
 ```lua
 vim.api.nvim_create_autocmd('User', { pattern = 'TSUpdate',
 callback = function()
@@ -189,6 +191,7 @@ end})
 Queries can be placed anywhere in your `runtimepath` under `queries/<language>`, with earlier directories taking precedence unless the queries are marked with `; extends`; see [`:h treesitter-query-modelines`](https://neovim.io/doc/user/treesitter.html#treesitter-query-modeline).
 
 E.g., to add queries for `zimbu`, put `highlights.scm` etc. under
+
 ```lua
 vim.fn.stdpath('data') .. 'site/queries/zimbu'
 ```