(conan-io#16195) Document bumping version

* Document bumping version

Signed-off-by: Uilian Ries <[email protected]>

* use specific section on docs

Signed-off-by: Uilian Ries <[email protected]>

* remove section from docs

Signed-off-by: Uilian Ries <[email protected]>

* grammar fix

Signed-off-by: Uilian Ries <[email protected]>

* Update docs/bump_version.md

Co-authored-by: Chris Mc <[email protected]>

* Update docs/bump_version.md

Co-authored-by: Chris Mc <[email protected]>

* Update docs/bump_version.md

Co-authored-by: Chris Mc <[email protected]>

* Update docs/bump_version.md

Co-authored-by: Chris Mc <[email protected]>

* Use official issue for new request

Signed-off-by: Uilian Ries <[email protected]>

* warning about bump version label

Signed-off-by: Uilian Ries <[email protected]>

* Update docs/bump_version.md

Co-authored-by: SSE4 <[email protected]>

---------

Signed-off-by: Uilian Ries <[email protected]>
Co-authored-by: Chris Mc <[email protected]>
Co-authored-by: SSE4 <[email protected]>

Author: 3 people

docs/README.md

@@ -13,6 +13,7 @@ When pull requests are merged, the CI will upload the generated packages to the
   + [Contributing to Conan Center Index](../CONTRIBUTING.md)
   + [Developing Recipes Locally](developing_recipes_locally.md)
   + [Adding Packages to ConanCenter](adding_packages/README.md) :point_left: Best place to learn how to contribute
+  + [Bumping versions to existing packages](bump_version.md)
   + [Errors from the conan-center hook (KB-Hxxx)](error_knowledge_base.md)
   + [Review Process](review_process.md)
   + [Labels](labels.md)

docs/bump_version.md

@@ -0,0 +1,48 @@
+# How to bump a package version for an existing recipe in ConanCenterIndex?
+
+Once a recipe is approved and merged to ConanCenterIndex, it may need to be updated with new versions released by the upstream.
+When someone needs a new package version that is not available in ConanCenterIndex, that person can open an issue [resquesting a new version](https://github.com/conan-io/conan-center-index/issues/new?assignees=&labels=upstream+update&template=package_upstream_update.yml&title=%5Brequest%5D+%3CLIBRARY-NAME%3E%2F%3CLIBRARY-VERSION%3E).
+Or, by opening a pull request changing and adding that needed version, this is called a `bump version`.
+The [build service](adding_packages/README.md#the-build-service) bumping process is limited to pull requests which **only** adds a new package version and nothing more. Removing older versions, or updating
+the recipe will disqualify a pull request from the `Bump version` [review process](review_process.md)
+
+## Choosing which version should be updated
+
+The first step is checking the version which should be added from the upstream. Please, avoid adding multiple versions which you do not
+need. Adding a new version will increase the building time and storage for each new package configuration.
+
+Once you detect which version should be updated, please, first check if the project `license` keeps the same.
+
+> In case you need to update attributes, dependencies versions, patches, or anything besides the package version in `conandata.yml` and `config.yml`,
+  then your pull request will not be classified as bump version.
+
+## What should be modified when bumping a version?
+
+Only the `config.yml` and `conandata.yml` should be updated with that new version:
+
+```yaml
+# config.yml
+versions:
+  "1.1.0":       <-- New version added. It should be protected by quotes
+    folder: all  <-- Folder name where conandata.yml is installed
+  "1.0.0":
+    folder: all
+```
+
+```yaml
+# all/conandata.yml
+sources:
+  "1.1.0":       <-- New version added
+    url: "https://example.com/repo/exameple-1.1.0.tar.gz"
+    sha256: "b3a24de97a8fdbc835b9833169501030b8977031bcb54b3b3ac13740f846ab30"
+  "1.0.0":
+    url: "https://example.com/repo/exameple-1.0.0.tar.gz"
+    sha256: "91844808532e5ce316b3c010929493c0244f3d37593afd6de04f71821d5136d9"
+```
+
+In case a patch should be re-used, it should be present in `conandata.yml` to the specific version as well.
+
+## Reviewing and merging
+
+Bumping version PRs follow the same regular [review process](review_process.md), except for being merged automatically
+as listed on [Labels](labels.md#bump-version) section.