docs: Document the existing deprecation policy

We recently renamed `jj util mangen` to `jj install-manpages` without a
deprecation warning, as it was missed in the initial PR. Waleed then
fixed it in a follow-up, which led to a longer discussion in the Discord which revealed that
not everyone was aware of it and _what_ requires a warning based deprecation.

This initially categorizes the policy into user-visible UX changes and small
impact renames, like for a small usergroup like packagers and third-party dependencies.
If we have more hickups with users, this can be expanded.

docs/contributing.md

@@ -82,6 +82,14 @@ existing component, we require an architecture review from  multiple
 stakeholders, which we do with [Design Docs](design_docs.md), see the
 [process here](design_docs.md#process).
 
+## Deprecating and removing commands
+
+Before removing a until now required argument, or making a optional argument
+required or even a user-visible command, make yourself familiar with our
+[Deprecation policy](deprecation.md). This makes the tool pleasant to use even
+if the hasn't reached a 1.0 yet. It allows changes like the `branch` to
+`bookmark` rename or the removal of `checkout` and `merge` to happen.
+
 ## Contributing to the documentation
 
 We appreciate [bug
@@ -110,7 +118,6 @@ directory](https://github.com/jj-vcs/jj/tree/main/cli/src/commands). Working
 on them requires setting up a Rust development environment, as described
 below, and may occasionally require adjusting a test.
 
-
 ## Learning Rust
 
 In addition to the [Rust Book](https://doc.rust-lang.org/book/) and the other

docs/deprecation.md

@@ -0,0 +1,23 @@
+# Deprecation Policy
+
+## User-facing commands and their arguments
+
+Whenever you rename a command or make a previously optional argument required,
+we require that you preserve the old command invocations keeps on working for 6
+months (so 6 releases, since we release monthly) with a deprecation message.
+The message should inform the user that the previous workflow is deprecated
+and to be removed in the future.
+
+## Packaging commands and niche commands
+
+For commands with a niche user audience or something we assume is rarely used
+(we sadly have no data), we take the liberity to remove the old behavior within
+two releases. This means that you can change the old command to immediately
+error.
+
+## Third-Party dependencies
+
+For third-party dependencies which previously were used for a core functionality
+like `libgit2` was before the `[git.subprocess]` option was added, we're free
+to remove most codepaths and move it to a `cargo` feature which we support
+up to 6 releases, this is to ease transition for package managers.

mkdocs.yml

@@ -131,6 +131,7 @@ nav:
       - 'Code of conduct': 'code-of-conduct.md'
       - 'Design Docs': 'design_docs.md'
       - 'Design Doc Blueprint': 'design_doc_blueprint.md'
+      - 'Deprecations': 'deprecations.md'
       - 'Temporary Voting for Governance': 'governance/temporary-voting.md'
 
 - 'Design docs':