From 304d808ff74d68da12802fb88417a255d5de269e Mon Sep 17 00:00:00 2001 From: Chris Mc Date: Tue, 30 Aug 2022 05:04:33 -0700 Subject: [PATCH] (#12687) docs: spelling and formatting --- docs/changelog.md | 44 +++++++++++++++++++++-------------- docs/code_of_conduct.md | 4 +--- docs/community_resources.md | 5 ++++ docs/consuming_recipes.md | 18 +++++++-------- docs/error_knowledge_base.md | 45 +++++++++--------------------------- docs/faqs.md | 22 ++++++++---------- docs/labels.md | 7 ++---- docs/review_process.md | 16 ++++++------- docs/v2_linter.md | 18 ++++++++------- docs/v2_migration.md | 7 ++---- docs/v2_roadmap.md | 21 +++++++++-------- 11 files changed, 95 insertions(+), 112 deletions(-) diff --git a/docs/changelog.md b/docs/changelog.md index 21ccd6be2d..d42fd18ec1 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -215,23 +215,25 @@ - [fix] Parse integer value when assigning properties. ### 18-October-2021 - 17:05 CEST - - [config] Upgrade Conan version to 1.40.4 - - [fix] Replace `Unauthorized User` label by `User-approval pending` - - [feat] Remove `os_build` and `arch_build` from generated profiles + +- [config] Upgrade Conan version to 1.40.4 +- [fix] Replace `Unauthorized User` label by `User-approval pending` +- [feat] Remove `os_build` and `arch_build` from generated profiles ### 11-October-2021 - 12:14 CEST - - [configs] Configurable Github statuses to check - - [configs] Pairing between configurations and workers (docker images, win/macos servers,...) is configurable in runtime. - - [feature] Early(iest) stop after failure: ignore any extra messages. It provides faster feedback for users. - - [feature] Skip stale pull-requests from automatic review requests. - - [feature] Add node-pool with more resources. It allows the CI to delegate certain builds that require higher RAM limits to it (configured manually). - - [fix] Removed EAP, now it should be named _"Access requests"_ everywhere - - [fix] Improved checks for infrastructure and configuration. It also fixes the auto-generated documentation for _"Supported platforms and configurations"_. - - [job] New job to remove dead branches from CI + +- [configs] Configurable Github statuses to check +- [configs] Pairing between configurations and workers (docker images, win/macos servers,...) is configurable in runtime. +- [feature] Early(iest) stop after failure: ignore any extra messages. It provides faster feedback for users. +- [feature] Skip stale pull-requests from automatic review requests. +- [feature] Add node-pool with more resources. It allows the CI to delegate certain builds that require higher RAM limits to it (configured manually). +- [fix] Removed EAP, now it should be named _"Access requests"_ everywhere +- [fix] Improved checks for infrastructure and configuration. It also fixes the auto-generated documentation for _"Supported platforms and configurations"_. +- [job] New job to remove dead branches from CI ### 01-October-2021 - 13:08 CEST -- [hotfix] Apply patch for https://github.com/conan-io/conan/issues/9695 (Added root certificate for Let's encrypt) +- [hotfix] Apply patch for (Added root certificate for Let's encrypt) ### 21-September-2021 - 12:09 CEST @@ -281,10 +283,10 @@ ### 01-June-2021 - 08:59 CEST - - [feature] RequestReviews: Add column to enable/disable review requests (any user). - - [testing] Use declared Conan version to run tests. - - [internal] Pay some technical debt. - - [internal] Simplify workflow, all packages already have properties. +- [feature] RequestReviews: Add column to enable/disable review requests (any user). +- [testing] Use declared Conan version to run tests. +- [internal] Pay some technical debt. +- [internal] Simplify workflow, all packages already have properties. ### 25-May-2021 - 13:42 CEST @@ -323,7 +325,7 @@ - [feature] Stop generating packages for apple-clang 9.1. - [feature] Raise error if `ConanInvalidConfiguration` is raised from `build()` method. - [feature] BuildSingleReference: All PRs use the new workflow. -- [feature] Allow modifications in the *.github* folder for GitHub bots and actions. +- [feature] Allow modifications in the _.github_ folder for GitHub bots and actions. - [feature] Use BuildSingleReference job to build packages (if needed) during a merge. - [feature] BuildSingleReference: Add build environment property to packages. - [feature] Tapaholes: Delete repositories after running jobs. @@ -540,27 +542,35 @@ - [fix] Fix checkExportSanity function ### 24-June-2020 - 10:55 CEST + - Updated Conan client to the 1.26.1 version in Windows and Mac agents. ### 18-June-2020 - 18:40 CEST + - Remove short paths limitation in all Windows agents. ### 04-June-2020 - 10:39 CEST + - Add `CONAN_SKIP_BROKEN_SYMLINKS_CHECK=1` in master jobs. ### 02-June-2020 - 13:06 CEST + - Avoid partial rebuilds in master jobs. Added `all_packages_done` property for every reference to track the completion of packages creation. ### 02-June-2020 - 00:02 CEST + - Updated CMake to 3.16.4 in Windows and Mac agents. ### 20-May-2020 - 10:34 CEST + - Updated Conan client to the 1.25.2 version in Windows and Mac agents. ### 14-May-2020 - 15:52 CEST + - Updated Conan client to 1.25.1 version in Windows and Mac agents. ### 13-May-2020 - 09:47 CEST (08e2be6) + - [refact] Simplify around ComputePackageID and CreatePackage - [refact] No need to pass 'winTmpPath' everywhere - Move the 'retryIze' call inside the scope of the node (Might improve [#1020](https://github.com/conan-io/conan-center-index/issues/1020)) diff --git a/docs/code_of_conduct.md b/docs/code_of_conduct.md index 72cfb41c92..fe533ead1e 100644 --- a/docs/code_of_conduct.md +++ b/docs/code_of_conduct.md @@ -1,6 +1,5 @@ # Code of conduct - Try to be polite, CCI maintainers and contributors are really willing to help and we enjoy it. Please keep in mind these points: @@ -15,5 +14,4 @@ Please keep in mind these points: - You should not get bothered if you feel unattended, CCI is an Open Source project, not a commercial product. Try to explain what you really need and we will try to help you. - - For possible violations of the CoC, please report to info@conan.io **and** conancenter@jfrog.com + For possible violations of the CoC, please report to info@conan.io **and** conancenter@jfrog.com diff --git a/docs/community_resources.md b/docs/community_resources.md index ee5a996bfb..6a09713749 100644 --- a/docs/community_resources.md +++ b/docs/community_resources.md @@ -5,9 +5,14 @@ This is a curated list of various bots and helpful tools that aim to making appr ## Contents + * [Social Media and More](#social-media-and-more) * [Bots](#bots) * [Tools](#tools) +## Social Media and More + +The community is very active on the [Cpplang's Slack channel](https://cpplang.slack.com/archives/C41CWV9HA), it's a great place to get help. + ## Bots - [Updatable Recipes](https://github.com/qchateau/conan-center-bot): Automatically scans available recipes and checked for new upstream releases and tests one configuration diff --git a/docs/consuming_recipes.md b/docs/consuming_recipes.md index 9bfa252e6d..c58bbc2e29 100644 --- a/docs/consuming_recipes.md +++ b/docs/consuming_recipes.md @@ -1,6 +1,6 @@ # Consuming recipes -Recipes in this repository are evolving continously, contributors are creating pull-requests +Recipes in this repository are evolving continuously, contributors are creating pull-requests fixing issues and adding new features every day. It is expected that from time to time these new recipe revisions stop to work in your project. @@ -41,7 +41,6 @@ There can be several root causes if a recipe (a new revision) stopped to work in features are using the required Conan version and testing the actual behavior of those features (feedback about them is very important to Conan). - ## Isolate your project from upstream changes There are two main ways you can isolate your project from changes in recipes: @@ -52,7 +51,6 @@ There are two main ways you can isolate your project from changes in recipes: * **Pin the version of every reference you consume in your project** using recipe revisions and lockfiles. - ### Use your own Artifactory instance Using your own Artifactory instance is not as complicated as it sounds. You can [deploy it @@ -63,11 +61,11 @@ using only that remote (`conan remote list`). Conan makes it easy to use differe per project (check `CONAN_USER_HOME` env variable) or to store the configuration in some external file or repository so you can shared and install it using one command (`conan config install ...`). - ### Use recipe revisions and lockfiles If you don't want to deploy and maintain your own Artifactory instance, you can isolate from -changes in upstream recipes in ConanCenter using [recipe revisions](https://docs.conan.io/en/latest/versioning/revisions.html) and [lockfiles](https://docs.conan.io/en/latest/versioning/lockfiles.html) (please, read linked Conan documentation for more detailed +changes in upstream recipes in ConanCenter using [recipe revisions](https://docs.conan.io/en/latest/versioning/revisions.html) +and [lockfiles](https://docs.conan.io/en/latest/versioning/lockfiles.html) (please, read linked Conan documentation for more detailed explanation). Recipe revisions and lockfiles can be used to define exactly the binary you want to use in @@ -80,13 +78,14 @@ is a hash added to the reference and can be used in Conan at the same place as r revisions: * In the command line: - ``` + + ```sh conan install openssl/3.0.1@#1955937e88f13a02aa4fdae98c3f9fb8 ``` * In a `conanfile.txt` file: - ```ini + ```txt [requires] openssl/3.0.1@#1955937e88f13a02aa4fdae98c3f9fb8 ``` @@ -113,19 +112,18 @@ The two basic commands you need to know ([full docs here](https://docs.conan.io/ * Create lockfile from `conanfile.txt` file: - ``` + ```sh conan lock create conanfile.txt --lockfile-out=locks/project.lock ``` * Consume a lockfile: - ``` + ```sh conan install conanfile.txt --lockfile=locks/project.lock ``` If your project is managing several configurations, you would probably like to have a look to [base lockfiles](https://docs.conan.io/en/latest/versioning/lockfiles/configurations.html#base-lockfiles) and [lockfile bundles](https://docs.conan.io/en/latest/versioning/lockfiles/bundle.html) in the documentation. - --- This repository will keep evolving, and Conan will release new features. Even if these breaking diff --git a/docs/error_knowledge_base.md b/docs/error_knowledge_base.md index 69ac026de1..bbea3128fd 100644 --- a/docs/error_knowledge_base.md +++ b/docs/error_knowledge_base.md @@ -1,6 +1,5 @@ # Errors from the conan-center hook (KB-Hxxx) - #### **#KB-H001: "DEPRECATED GLOBAL CPPSTD"** `Conan > 1.15` deprecated the usage of the global ``cppstd`` setting in favor of ``compiler.cppstd`` to [manage C++ standard](https://docs.conan.io/en/latest/howtos/manage_cpp_standard.html). As a subsetting of the compiler, it shouldn't be declared in the `conanfile.py`. @@ -11,7 +10,8 @@ The package names in conan-center have to be [lowercase](https://github.com/cona #### **#KB-H003: "RECIPE METADATA"** -The recipe has to declare the following attributes: +The recipe has to declare the following attributes: + - [url](https://docs.conan.io/en/latest/reference/conanfile/attributes.html#url) - [license](https://docs.conan.io/en/latest/reference/conanfile/attributes.html#license) - [description](https://docs.conan.io/en/latest/reference/conanfile/attributes.html#description) @@ -61,12 +61,10 @@ class SomeRecipe(ConanFile): Here we use [configure()](https://docs.conan.io/en/latest/reference/conanfile/methods.html#configure-config-options) method, because user options are loaded after [config_options()](https://docs.conan.io/en/latest/reference/conanfile/methods.html#configure-config-options) only. - #### **#KB-H008: "VERSION RANGES"** It is not allowed to use [version ranges](https://docs.conan.io/en/latest/versioning/version_ranges.html) for the recipes in Conan center, where the dependency graph should be deterministic. - #### **#KB-H009: "RECIPE FOLDER SIZE"** The recipe folder (including the `test_package` folder) cannot exceed 256KB. @@ -257,29 +255,8 @@ class TestConan(ConanFile): #### **#KB-H030: "CONANDATA.YML FORMAT"** -The structure of the [conandata.yml](https://docs.conan.io/en/latest/reference/config_files/conandata.yml.html) file should follow this schema: - -```yml -sources: - "1.69.0": - url: "url1.69.0" - sha256: "sha1.69.0" - "1.70.0": - url: "url1.70.0" - sha256: "sha1.70.0" -patches: - "1.70.0": - - patch_file: "001-1.70.0.patch" - base_path: "source_subfolder/1.70.0" - - url: "https://fake_url.com/custom.patch" - sha256: "sha_custom" - base_path: "source_subfolder" - "1.71.0": - - patch_file: "001-1.71.0.patch" - base_path: "source_subfolder/1.71.0" -``` - -See also: [The conandata.yml](how_to_add_packages.md#the-conandatayml). +The structure of the [conandata.yml](https://docs.conan.io/en/latest/reference/config_files/conandata.yml.html) file should follow the schema +defined in [Adding Packages - `Conandata.yml` Format](conandata_yml_format.md). #### **#KB-H031: "CONANDATA.YML REDUCE"** @@ -347,7 +324,8 @@ It's important to have new library version defined in both [config.yml](how_to_a #### **#KB-H053: "PRIVATE IMPORTS"** -The recipe imports private Conan API, this is strongly discouraged - private imports are subjects to breaking changes. Avoid usage of private APIs, request to publically expose needed methods, if necessary. +The recipe imports private Conan API, this is strongly discouraged - private imports are subjects to breaking changes. Avoid usage of private APIs, +request to publicly expose needed methods, if necessary. #### **#KB-H054: "LIBRARY DOES NOT EXIST"** @@ -466,15 +444,15 @@ class SomeRecipe(ConanFile): def package_id(self): self.info.header_only() ``` - + There is the case when the package is header-only, but the options affects the generated artifact, (e.g. kanguru, pagmo2 ...), so you need to use `self.info.settings.clear()` instead. - + - For "tool" recipes ([example](https://github.com/conan-io/conan-center-index/blob/e604534bbe0ef56bdb1f8513b83404eff02aebc8/recipes/cmake/3.x.x/conanfile.py#L104-L105)) which only provide binaries, see [our packing policy](packaging_policy.md#settings) for more, should do as follows: ```python def package_id(self): del self.info.settings.compiler - ``` + ``` #### **#KB-H071: "INCLUDE PATH DOES NOT EXIST"** @@ -485,11 +463,10 @@ def package_info(self): self.cpp_info.includedirs = [] ``` -# Deprecated errors +## Deprecated errors The following errors from the hooks are deprecated and no longer reported: -#### **#KB-H047: "NO ASCII CHARACTERS"** +### **#KB-H047: "NO ASCII CHARACTERS"** According to PEP [263](https://www.python.org/dev/peps/pep-0263/), Unicode literals should only appear in Python code if the encoding is declared on one of the first two lines of the source file. Without such a declaration, any Unicode literal will cause a syntax error for Python 2 interpreters. - diff --git a/docs/faqs.md b/docs/faqs.md index 69ad6f6638..d69b2aaa24 100644 --- a/docs/faqs.md +++ b/docs/faqs.md @@ -119,7 +119,7 @@ As described in the [Supported platforms and configurations](supported_platforms * For security reasons, most companies build their own packages from sources, even if they already have a pre-built version available, which further reduces the need for extra configurations; * Each recipe results in around 130 packages, and this is only for x86_64, but not all packages are used, some settings remain with zero downloads throughout their life. So, imagine adding more settings that will rarely be used, but that will consume more resources as time and storage, this leaves us in an impractical situation. -#### But if there are no packages available, what will the x86 validation look like? +### But if there are no packages available, what will the x86 validation look like? As stated earlier, any increase in the number of configurations will result in an impractical scenario. In addition, more validations require more review time for a recipe, which would increase the time for all PRs, delaying the release of a new package. For these reasons, x86 is not validated by the CCI. @@ -131,7 +131,7 @@ The project initially decided not to support the PDB files primarily due to the However, there are ways to get around this, one of them is through the [/Z7](https://docs.microsoft.com/en-us/cpp/build/reference/z7-zi-zi-debug-information-format) compilation flag, which can be passed through [environment variables](https://docs.microsoft.com/en-us/cpp/build/reference/cl-environment-variables). You can use your [profile](https://docs.conan.io/en/latest/reference/profiles.html#package-settings-and-env-vars) to customize your compiler command line. -#### Why is there no option for PDB, as there is for fPIC? +### Why is there no option for PDB, as there is for fPIC? Adding one more common option, it seems the most simple and obvious solution, but it contains a side effect already seen with fPIC. It is necessary to manage the entire recipe, it has become a Boilerplate. So, adding PDB would be one more point to be reviewed for each recipe. In addition, in the future new options could arise, such as sanity or benchmark, further inflating the recipes. For this reason, a new option will not be added. However, the inclusion of the PDB files is discussed in issue [#1982](https://github.com/conan-io/conan-center-index/issues/1982) and there are some ideas for making this possible through a new feature. If you want to comment on the subject, please visit issue. @@ -164,27 +164,26 @@ and [libcurl](https://github.com/conan-io/conan-center-index/blob/f834ee1c825641 However, if logic is too complex (this is subjective and depends on the Conan review team) then just remove the option. After one month, we will welcome a PR removing the option that was deprecated. - ## Can I split a project into an installer and library package? No. Some projects provide more than a simple library, but also applications. For those projects, both libraries and executables should be kept together under the same Conan package. In the past, we tried to separate popular projects, like Protobuf, and it proved to be a complex and hard task to be maintained, requiring custom patches to disable parts of the building. Also, with the [context](https://docs.conan.io/en/latest/systems_cross_building/cross_building.html#conan-v1-24-and-newer) feature, we can use the same package as build requirement, for the same build platform, and as a regular requirement, for the host platform, when cross-building. It's recommended using 2 profiles in that case, one for build platform (where the compilation tools are being executed) and one for host platform (where the generated binaries will run). ## What license should I use for Public Domain? -[The Public Domain](https://fairuse.stanford.edu/overview/public-domain/welcome/) is not a license by itselt. Thus, we have [equivalent licenses](https://en.wikipedia.org/wiki/Public-domain-equivalent_license) to be used instead. By default, if a project uses Public Domain and there is no offcial license listed, you should use [Unlicense](https://spdx.org/licenses/Unlicense). +[The Public Domain](https://fairuse.stanford.edu/overview/public-domain/welcome/) is not a license by itself. Thus, we have [equivalent licenses](https://en.wikipedia.org/wiki/Public-domain-equivalent_license) to be used instead. By default, if a project uses Public Domain and there is no official license listed, you should use [Unlicense](https://spdx.org/licenses/Unlicense). ## What license should I use for a custom project specific license? When a non standard open-source license is used, we have decided to use `LicenseRef-` as a prefix, followed by the name of the file which contains a custom license. See [the reviewing guidlines](reviewing.md#license-attribute) for more details. -## Why is a `tools.check_min_cppstd` call not enough? +## Why is a `build.check_min_cppstd` call not enough? Very often C++ projects require a minimum standard version, such as 14 or 17, in order to compile. Conan offers tools which enable checking the relevant setting is enabled and above this support for a certain version is present. Otherwise, it uses the compiler's default. ```python def configure(self): - tools.check_min_cppstd(self, 14) 👈 Wrong! + build.check_min_cppstd(self, 14) 👈 Wrong! ``` This fails to cover the vast number of use cases for the following reasons: @@ -196,11 +195,11 @@ This fails to cover the vast number of use cases for the following reasons: ```python def validate(self): # 👇 Correct - if self.settings.compiler.get_safe("cppstd"): - tools.check_min_cppstd(self, 14) + if self.settings.compiler.cppstd: + build.check_min_cppstd(self, 14) ``` -As a result, all calls to `tools.check_min_cppstd` must be guarded by a check for the setting and the only way to ensure the C++ standard is to check the compiler's version to know if it offers sufficient support. An example of this can be found [here](https://github.com/conan-io/conan/issues/8002). +As a result, all calls to `build.check_min_cppstd` must be guarded by a check for the setting and the only way to ensure the C++ standard is to check the compiler's version to know if it offers sufficient support. An example of this can be found [here](https://github.com/conan-io/conan/issues/8002). ## What is the policy for adding older versions of a package? @@ -291,8 +290,7 @@ instead, the libraries that depend on *MKL*, *IPP* or *DNN* should use the follo * `intel-ipp/`, e.g. `intel-ipp/2021` * `intel-dnn/`, e.g. `intel-dnn/2021` -**NOTE**: These references are not available in ConanCenter and will likely never be! it's the consumer's responsibility to provide the recipes for these libraries. - +**Note**: These references are not available in ConanCenter and will likely never be! it's the consumer's responsibility to provide the recipes for these libraries. Since these references will be never available in ConanCenter, they will be deactivated in the consuming recipes by default: @@ -382,7 +380,7 @@ In order to consume all those libraries as shared ones, building from sources is easily achievable using `*:shared=True` in the _host_ profile and `--build` in the install command. With these inputs, Conan will build from sources all the packages and use the shared libraries when linking. -> ℹī¸ Note: If you are hosting your own recipes, the proper solution for recipes would be to use something like +> **Note**: If you are hosting your own recipes, the proper solution for recipes would be to use something like > [`shared_library_package_id`](https://docs.conan.io/en/latest/reference/conanfile/methods.html?highlight=shared_library_package_id#self-info-shared-library-package-id), > that will encode this information in the package ID and ensure that any change in the static libraries that are > embedded into a shared one is taken into account when computing the package ID. diff --git a/docs/labels.md b/docs/labels.md index 4ad9432b69..129664ab09 100644 --- a/docs/labels.md +++ b/docs/labels.md @@ -14,12 +14,11 @@ special meaning: * [Unexpected Error](#unexpected-error) * [User-approval pending](#user-approval-pending) - ## Bump dependencies Label [`Bump dependencies`](https://github.com/conan-io/conan-center-index/pulls?q=is%3Aopen+is%3Apr+label%3A%22Bump+dependencies%22+) is assigned by the bot to pull-requests that are just upgrading the version of the requirements that were already in the -recipe. +recipe. > These pull-requests will be merged right away without requiring any approval (CI and CLA checks must have passed). @@ -52,7 +51,7 @@ any further activity. Label [`Unexpected Error`](https://github.com/conan-io/conan-center-index/pulls?q=is%3Aopen+is%3Apr+label%3A%22Unexpected+Error%22) is assigned by the CI when the process finishes abnormally. It tries to signal all the pull requests that failed, but -didn't provide any meaninful message to the user. Usually it is some _random_ internal error and it won't happen next +didn't provide any meaningful message to the user. Usually it is some _random_ internal error and it won't happen next time the CI runs, don't hesitate to trigger a new build in this situation. ## User-approval pending @@ -60,5 +59,3 @@ time the CI runs, don't hesitate to trigger a new build in this situation. Label [`User-approval pending`](https://github.com/conan-io/conan-center-index/pulls?q=is%3Aopen+is%3Apr+label%3A%22User-approval+pending%22) signals the pull request that have been submitted by an user who is not yet approved in ConanCenter. Once the user is approved these pull requests will be triggered again automatically. - - diff --git a/docs/review_process.md b/docs/review_process.md index 177430e94e..d746d332e8 100644 --- a/docs/review_process.md +++ b/docs/review_process.md @@ -51,7 +51,7 @@ If you struggle to fix build errors yourself, you may want to ask for help from ### Unexpected error Sometimes, build fails with `Unexpected error` message. This indicates an infrastructure problem, and usually it's unrelated to the changes within PR itself. -Keep in mind conan-center-index is still _under development_, and there can be some instabilities. Especially, as we're using lots of external services, +Keep in mind conan-center-index is still *under development*, and there can be some instabilities. Especially, as we're using lots of external services, which might be inaccessible (GitHub API, docker hub, etc.) and may result in intermittent failures. So, what to do once `Unexpected error` was encountered? You may consider re-running the build by closing your pull request, waiting 15 seconds, and then re-opening it again. @@ -63,7 +63,7 @@ Alternatively, just [open a new issue](https://github.com/conan-io/conan-center- Right now, neither GitHub itself nor conan-center-bot notify about merge conflicts, so it's the contributor's responsibility to periodically check for the conflicts. Pull Requests that have merge conflicts can't be merged, and all the conflicts have to be resolved first. -Please [synchronize your branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) to take into account the latest changes in the main branch. This is importatnt for ConanCenter to ensure it is building the correct recipe revision, see [this comment](https://github.com/conan-io/conan-center-index/pull/8797#discussion_r781993233) for details. One trick is to look out for comments from the [Community's Conflict PR Bot](https://github.com/prince-chrismc/conan-center-index/blob/patch-41/docs/community_resources.md#bots) which can anticipate possible problems. +Please [synchronize your branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) to take into account the latest changes in the main branch. This is important for ConanCenter to ensure it is building the correct recipe revision, see [this comment](https://github.com/conan-io/conan-center-index/pull/8797#discussion_r781993233) for details. One trick is to look out for comments from the [Community's Conflict PR Bot](https://github.com/prince-chrismc/conan-center-index/blob/patch-41/docs/community_resources.md#bots) which can anticipate possible problems. ## Draft @@ -105,7 +105,7 @@ The list includes conan-center-index contributors who are very active and proven - [@MartinDelille](https://github.com/MartinDelille) - [@dmn-star](https://github.com/dmn-star) -The list, located [here](https://github.com/conan-io/conan-center-index/blob/master/.c3i/reviewers.yml), +The list, located [here](../.c3i/reviewers.yml), is not constant and will change periodically based on contribution. That also means **you can be included in this list** as well - submit PRs and provide reviews, and in time you may be added as a trusted contributor. @@ -115,9 +115,9 @@ At least 2 approving reviews are required, and at least one of them has to be fr So, it might be 1 official + 1 community, or 2 official, but it couldn't be just 2 community reviews. Approvals are only counted if they are associated with the latest commit in the PR, while "Change requested" ones (from the Conan team) will persist even if there are new commits. Don't hesitate to dismiss old reviews if the issues have already been addressed. -> **Note.-** Pull requests labelled as [`Bump version`](https://github.com/conan-io/conan-center-index/pulls?q=is%3Aopen+is%3Apr+label%3A%22Bump+version%22) +> **Note** Pull requests labelled as [`Bump version`](https://github.com/conan-io/conan-center-index/pulls?q=is%3Aopen+is%3Apr+label%3A%22Bump+version%22) > or [`Bump dependencies`](https://github.com/conan-io/conan-center-index/pulls?q=is%3Aopen+is%3Apr+label%3A%22Bump+dependencies%22+) are merged by -> the bot without requiring any approval. +> the bot without requiring any approval. ### Reviews from others @@ -144,7 +144,7 @@ PR is selected for the merge only if: If these conditions are fulfilled, the PR is merged (associated issues are automatically closed), and then the build of `master` is launched. -The conan-center-bot will perform a [squash and merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-pull-request-commits). You don't need to rebase +The conan-center-bot will perform a [squash and merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-pull-request-commits). You don't need to rebase your pull request, we ask you not to do it because it will dismiss any reviews and the reviewer will need to restart. ### Merge @@ -159,7 +159,7 @@ So we really appreciate it if changes in `master` to the same recipe are already New packages are promoted from the internal repository to ConanCenter. This process is an internal Artifactory promotion that is quite fast, nevertheless there are some caches and CDNs that need to be invalidated and propagated before the package is finally available for consumption. -The process can take several minutes, so please, consider a _grace period_ and understand that the package won't be available inmediately. +The process can take several minutes, so please, consider a *grace period* and understand that the package won't be available immediately. ### Updating web front end @@ -170,4 +170,4 @@ That may explain the fact there are moments when the information showed in the f ## Stale PRs -Conan Center Index uses [stale bot](https://github.com/probot/stale) to close abandoned pull requests. It's configured by [stale.yml](.github/stale.yml). When a pull request gets stale, we encourage anyone to take ownership of the PR (even submit changes to the author's branch if possible) so existing work doesn't get lost when the pull request is closed without merging. +Conan Center Index uses [stale bot](https://github.com/probot/stale) to close abandoned pull requests. It's configured by [stale.yml](../.github/stale.yml). When a pull request gets stale, we encourage anyone to take ownership of the PR (even submit changes to the author's branch if possible) so existing work doesn't get lost when the pull request is closed without merging. diff --git a/docs/v2_linter.md b/docs/v2_linter.md index bdb6cc0d10..5d988acb47 100644 --- a/docs/v2_linter.md +++ b/docs/v2_linter.md @@ -1,22 +1,24 @@ -Linter to help migration to Conan v2 -==================================== +# Linter to help migration to Conan v2 ## Contents - * [Import ConanFile from `conan`](#import-conanfile-from-conan) - * [Import tools from `conan`](#import-tools-from-conan) +- [Linter to help migration to Conan v2](#linter-to-help-migration-to-conan-v2) + - [Contents](#contents) + - [Import ConanFile from `conan`](#import-conanfile-from-conan) + - [Import tools from `conan`](#import-tools-from-conan) + - [Disable linter for a specific conanfile](#disable-linter-for-a-specific-conanfile) On our [path to Conan v2](v2_roadmap.md) we are leveraging on custom Pylint rules. This linter will run for every pull-request that is submitted to the repository and will raise some warnings and errors that should be addressed in order to migrate the recipes to Conan v2. -It is important to note that these rules are targetting Conan v2 compatibility layer, their +It is important to note that these rules are targeting Conan v2 compatibility layer, their purpose is to fail for v1 syntax that will be no longer available in v2. Even if the syntax if perfectly valid in Conan v1, the recipe might fail here because it is not v2-compliant. -> **Note.-** Some of the errored checks might be just plain Python syntax errors, while +> **Note** Some of the errored checks might be just plain Python syntax errors, while > others might be related to the custom rules added by us. Here you can find some examples of the extra rules we are adding: @@ -64,13 +66,13 @@ Here is a list of different imports and their new equivalent (note that the inte | conans.errors.ConanInvalidConfiguration | [conan.errors.ConanInvalidConfiguration](https://docs.conan.io/en/latest/migrating_to_2.0/recipes.html#migrating-the-recipes) | 1.47.0 | | conans.errors.ConanException | [conan.errors.ConanException](https://docs.conan.io/en/latest/migrating_to_2.0/recipes.html#migrating-the-recipes) | 1.47.0 | - -# Disable linter for a specific conanfile +## Disable linter for a specific conanfile If for some reason a conanfile of a recipe or a test_package is not yet prepared to pass all the checks of the linter, it can be skipped from `pylint` adding the following comment to the file: **`conanfile.py`** + ```python # pylint: skip-file from conans import ConanFile, CMake, tools diff --git a/docs/v2_migration.md b/docs/v2_migration.md index 58b2e63211..c38d114a5c 100644 --- a/docs/v2_migration.md +++ b/docs/v2_migration.md @@ -48,7 +48,7 @@ We will cover some cases of porting all the information set with the current mod new one. To read more about the properties available for each generator and how the properties model work, please check the [Conan documentation](https://docs.conan.io/en/latest/conan_v2.html#editables-don-t-use-external-templates-any-more-new-layout-model). -> ⚠ī¸ **Note**: Please, remember that the **new** ``set_property`` and the **current** attributes +> **Note**: Please, remember that the **new** ``set_property`` and the **current** attributes > model are *completely independent since Conan 1.43*. Setting ``set_property`` in recipes will > not affect current CMake 1.X generators (``cmake``, ``cmake_multi``, ``cmake_find_package`` and > ``cmake_find_package_multi``) at all. @@ -198,7 +198,7 @@ class ExpatConan(ConanFile): ... ``` -> ⚠ī¸ **Note**: There are more cases in which you probably want to set the +> *Note**: There are more cases in which you probably want to set the > ``cmake_find_mode`` property to ``both``. For example, for the libraries which [find > modules files are included in the CMake > distribution](https://cmake.org/cmake/help/latest/manual/cmake-modules.7.html#find-modules). @@ -355,7 +355,6 @@ class TensorflowLiteConan(ConanFile): ... ``` - ### Translating .build_modules to cmake_build_modules Previously we saw that some recipes use a build module with an alias to set an arbitrary target name. @@ -389,8 +388,6 @@ class PyBind11Conan(ConanFile): ``` - - ### PkgConfigDeps The case of ``PkgConfigDeps`` is much more straight forward than the ``CMakeDeps`` case. diff --git a/docs/v2_roadmap.md b/docs/v2_roadmap.md index b666bf64a4..99e93b1464 100644 --- a/docs/v2_roadmap.md +++ b/docs/v2_roadmap.md @@ -19,9 +19,9 @@ * [Webpage with v2 information](#webpage-with-v2-information) * [Future](#future) -> ⚠ī¸ **Note.-** This document is not a [guide about how to migrate recipes to Conan v2](v2_migration.md). +> **Note** This document is not a [guide about how to migrate recipes to Conan v2](v2_migration.md). -> ⚠ī¸ **Note.-** This is a working document that will be updated as we walk +> **Note** This is a working document that will be updated as we walk > this path. There are no dates intentionally, and if any they should be > considered as an estimation, there are still some unknowns to provide > certain steps and dates. @@ -32,17 +32,17 @@ recipes and users, and we are willing to adopt it. It is a new major version that will come with many breaking changes. Lot of the features and syntax that we were used to in Conan v1 will no longer -be available and will be superseeded by improved alternatives. All these +be available and will be supersedes by improved alternatives. All these alternatives should be backported to v1.x releases, so **there will be a subset of features that will work using Conan v1 and v2**. **Our main goal in ConanCenter during this migration process is to ensure that recipes work with v1 and v2** and to make the transition as smooth as -possible for contributors and users. In the end we will be providing +possible for contributors and users. In the end we will be providing working recipes and binaries for both versions. This process will require a lot of work also in the internals, we will keep -communicating those changes and the relevant updates in the +communicating those changes and the relevant updates in the [changelog](changelog.md). Here there are the main steps that we are planning for the following months. @@ -50,9 +50,9 @@ planning for the following months. ### Prepare the CI infrastructure -Workers for Conan v2 will be ready for Windows, Macos and Linux alternatives. -[Modern docker images](https://github.com/conan-io/conan-docker-tools/tree/master/modern) with Conan v2 are already -available to use, for example `conanio/gcc11-ubuntu16.04:2.0.0-pre`. +Workers for Conan v2 will be ready for Windows, Macos and Linux alternatives. +[Modern docker images](https://github.com/conan-io/conan-docker-tools/tree/master/modern) with Conan v2 are already +available to use, for example `conanio/gcc11-ubuntu16.04:2.0.0-pre`. Note that we will be using tag name `2.0.0-pre` until there is an actual Conan v2 release, this tag will use the latest pre-release available (alpha, beta or release candidate). @@ -60,7 +60,7 @@ available (alpha, beta or release candidate). ### Export recipes using Conan v2 (warning) We will start to run `conan export` using Conan v2 and the result will be -added to the comments by the bot. Failing this command won't make the +added to the comments by the bot. Failing this command won't make the pull-request fail at this moment, but we expect contributors to start gaining awareness about changes in Conan v2. @@ -69,13 +69,14 @@ gaining awareness about changes in Conan v2. We want to provide a Conan recipe's linter in this repository. We will add warnings and errors to it following the pace dictated by the community. The purpose is that this linter will fail pull-requests if there is any -error and, this way, we can start to migrate small (and easy) bits of +error and, this way, we can start to migrate small (and easy) bits of recipes... and ensure that future pull-requests don't introduce regressions. This linter can (and surely will) implement some of the checks that are being currently done by [hooks](https://github.com/conan-io/hooks), but the purpose is not replace them: + * hooks are really useful from the CLI, and are easier to install and run. * linter provides much better output in GitHub interface.