Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Update versioning policy #24411

Merged
merged 2 commits into from
Nov 5, 2024
Merged

docs: Update versioning policy #24411

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dca1739
Update versioning policy
AbrilRBS Jun 21, 2024
ee503ea
Missing patch
AbrilRBS Sep 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 0 additions & 7 deletions docs/adding_packages/conandata_yml_format.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -219,7 +219,6 @@ Usually, the following kind of problems are good candidates for backports:
* Data corruption.
* Use of outdated or deprecated API or library.

As sources with backports don't act exactly the same as the version officially released, it may be a source of confusion for the consumers who are relying on the buggy behavior (even if it's completely wrong). Therefore, it's required to introduce a new `cci.<YYYYMMDD>` version for such backports, so consumers may choose to use either official version, or modified version with backport(s) included.

#### patch_source

Expand All @@ -235,9 +234,3 @@ _Recommended_

For the `patch_type: portability` there might be no patch source matching the definition above. Although we encourage contributors to submit all such portability fixes upstream first, it's not always possible (e.g. for projects no longer maintained). In that case, a link to the Conan issue is a valid patch source (if there is no issue, you may [create](https://github.com/conan-io/conan-center-index/issues/new/choose) one).
For the `patch_type: conan`, it doesn't make sense to submit patch upstream, so there will be no patch source.

#### base_path

_Optional_

Specifies a sub-directory in project's sources to apply patch. This directory is relative to the [source_folder](https://docs.conan.io/1/reference/conanfile/attributes.html?highlight=source_folder#source-folder). Usually, it would be a `source_subfolder`, but could be a lower-level sub-directory (e.g. if it's a patch for a submodule).
36 changes: 19 additions & 17 deletions docs/adding_packages/conanfile_attributes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,50 +38,52 @@ Please see the FAQs for:

### Version

ConanCenter is geared towards quickly added new release, the build service always pass the version it is currently building to the recipe.
The `version` attribute MUST NOT be added to any recipe - with exception to "system packages".

#### ConanCenter specific releases format

The notation shown below is used for publishing packages which do not match the original library's official releases. This format which includes the "datestamp" corresponding to the date of a commit: `cci.<YEAR MONTH DAY>`.
The notation shown below is used for publishing packages which do not match the original library's official releases.

In order to create reproducible builds, we also "commit-lock" to the latest commit on that day. Otherwise, users would get inconsistent results over time when rebuilding the package. An example of this is the [RapidJSON](https://github.com/Tencent/rapidjson) library, where its package reference is `rapidjson/cci.20200410` and its sources are locked the latest commit on that date in [config.yml](https://github.com/conan-io/conan-center-index/blob/master/recipes/rapidjson/config.yml#L4). The prefix `cci.` is mandatory to distinguish as a virtual version provided by CCI. If you are interested to know about the origin, please, read [here](https://github.com/conan-io/conan-center-index/pull/1464).
There are two cases to consider:

* The library has not had any previous releases/tags. In this case, the version should be of the form
`0.0.0.cci.<YEAR MONTH DAY>`. For example, `0.0.0.cci.20240402`. When/if a version of the library is ever released.
this will allow version ranges to properly identify the release as a newer version.
* The library has had previous releases/tags. In this case, the version should be of the form
`<MAJOR>.<MINOR>.<PATCH>.cci.<YEAR MONTH DAY>`. For example, `1.2.0.cci.20240402`.
This will allow version ranges to properly identify the release as a newer version.

In order to create reproducible builds, we also "commit-lock" to the latest commit on that day, so the sources should point
to the commit hash of that day. Otherwise, users would get inconsistent results over time when rebuilding the package.

### License Attribute

The license attribute is a mandatory field which provides the legal information that summarizes the contents saved in the package. These follow the
[SPDX license](https://spdx.org/licenses/) as a standard. This is for consummers, in particular in the enterprise sector, that do rely on SDPX compliant identifiers so that they can flag this as a custom license text.
[SPDX license](https://spdx.org/licenses/) as a standard. This is for consumers, in particular in the enterprise sector, that do rely on SDPX compliant identifiers so that they can flag this as a custom license text.

* If the library has a license that has a SPDX identifier, use the [short Identifiers](https://spdx.dev/ids/).
* If the library has a license text that does not match a SPDX identifier, including custom wording disclaiming copyright or dedicating the words to the ["public domain"](https://fairuse.stanford.edu/overview/public-domain/welcome/), use the [SPDX License Expressions](https://spdx.github.io/spdx-spec/v2-draft/SPDX-license-expressions/), this can follow:
* `LicenseRef-` as a prefix, followed by the name of the library. For example:`LicenseRef-libfoo-public-domain`
* If the license is extracted from a specific document, prepend `DocumentRef-<filename>-` to the license name. For example: `DocumentRef-README.md-LicenseRef-libfoo-public-domain`
* If the library makes no mention of a license and the terms of use - it **shall not be accepted in ConanCenter** , even if the code is publicly available in GitHub or any other platforms.

In case the license changes in a new release, the recipe should update the license attribute accordingly:

```python
class LibfooConan(ConanFile):
license = ("MIT", "BSD-3-Clause") # keep both old and new licenses, so conan inspect can find it
license = "MIT"

def configure (self):
# change the license according to the version, so conan graph info can show the correct one

# INFO: Version < 2.0 the license was MIT, but changed to BSD-3-Clause now.
self.license = "BSD-3-Clause" if Version(self.version) >= "2.0.0" else "MIT"
if Version(self.version) >= "2.0.0":
self.license = "BSD-3-Clause"
```

## Order of methods and attributes

Prefer the following order of documented methods in python code (`conanfile.py`, `test_package/conanfile.py`):

For `conan create` the order is listed [here](https://docs.conan.io/1/reference/commands/creator/create.html#methods-execution-order)
test packages recipes should append the following methods:

* deploy
* test

the order above resembles the execution order of methods on CI. therefore, for instance, `build` is always executed before `package` method, so `build` should appear before the
`package` in `conanfile.py`.
For `conan create` the order is listed [here](https://docs.conan.io/2/reference/commands/create.html#methods-execution-order).

## Settings

Expand Down Expand Up @@ -141,7 +143,7 @@ Having the same naming conventions for the options helps consumers. It allows us
### Predefined Options and Known Defaults

ConanCenter supports many combinations, these are outline in the [supported configurations](../supported_platforms_and_configurations.md) document for each platform.
By default recipes should use `shared=False` with `fPIC=True`. If support, `header_only=False` is the default.
By default recipes should use `shared=False` with `fPIC=True`. If supported, `header_only=False` is the default.

Usage of each option should follow the rules:

Expand Down
Loading