diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 22027379ce..8a8847b489 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,27 +11,28 @@ The following summarizes the process for contributing to the CCI (Conan Center I ## Community -Conan Center Index is an Open Source MIT licensed project. -Conan Center Index is developed by the Conan maintainers and a great community of contributors. +ConanCenterIndex is an Open Source MIT licensed project; it is developed by the Conan maintainers and a great community of contributors. ## Dev-flow & Pull Requests CCI follows the ["GitFlow"](https://datasift.github.io/gitflow/IntroducingGitFlow.html) branching model. Issues are triaged and categorized mainly by type (package request, bug...) and priority (high, medium...) using GitHub - labels. +labels. To contribute follow the next steps: 1. Comment in the corresponding issue that you want to contribute the package/fix proposed. If there is no open issue, we strongly suggest - to open one to gather feedback. -2. Check the [how_to_add_packages.md](docs/how_to_add_packages.md) if are - contributing for a new package. -3. Fork the [CCI repository](https://github.com/conan-io/conan-center-index) and create a `package/xxx` branch from the `master` branch and develop + opening one to gather feedback. +2. Get setup by following [Developing Recipes](docs/developing_recipes_locally.md) guide and learn the basic commands. +3. Check the [How To Add Packages](docs/how_to_add_packages.md) for the break down ConanCenterIndex specific conventions and practices. +4. In your fork create a `package/xxx` branch from the `master` branch and develop your fix/packages as discussed in previous step. -4. Try to keep your branch updated with the `master` branch to avoid conflicts. -5. Add the text (besides other comments): "fixes #IssueNumber" in the body of the PR, referring to the issue of step 1. +5. [Submit a pull request](docs/how_to_add_packages.md#submitting-a-package) once you are ready. This can be when you + got everything working or even if you need help. Add the text to the issue body (besides other comments): "fixes #IssueNumber" + in the body of the PR, referring to the issue of step 1. -The ``conan-io`` organization maintainers will review and help with the packaging. +The Conan Community works hard to review all the pull requests and provided assistance where need. +The [Review Process](docs/review_process.md) is partially automated with the help of @conan-center-index-bot :rocket: ## Issues @@ -50,10 +51,5 @@ For any suggestion, feature request or question open an issue indicating the fol - Try to explain the motivation, what are you trying to do, what is the pain it tries to solve. - What do you expect from CCI. -We use the following tags to control the status of the issues: - -- **infrastructure**: Waiting on tools or services belonging to the infra. -- **library request**: Request a new package to be created. -- **question**: Further information is requested . -- **upstream update**: Bump a new package version. -- **conan.io/center**: Issues and features related to Web UI . +We use the following tags to control the status of the issues and pull requests, you can learn more in [Labels](docs/labels.md) document +which details the important one and their roles. diff --git a/docs/README.md b/docs/README.md index bd72287edf..fa7ea9eebb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,5 +1,9 @@ +This repository, ConanCenterIndex, contains recipes for the remote [JFrog ConanCenter](https://conan.io/center/). +This remote is added by default to a clean installation of the Conan client. Recipes are contributed by opening pull requests as explained in the sections below. +When pull requests are merged, the CI will upload the generated packages to the [ConanCenter](https://conan.io/center/) remote. + # Documentation * [Code of conduct](code_of_conduct.md) @@ -7,14 +11,13 @@ * User documentation + [Contributing to Conan Center Index](../CONTRIBUTING.md) - + [Adding Packages to ConanCenter](how_to_add_packages.md) - + [Policy about patching](policy_patching.md) - + [Review Process](review_process.md) - + [Packaging policy](packaging_policy.md) - + [Supported platforms and configurations](supported_platforms_and_configurations.md) + + [Developing Recipes Locally](developing_recipes_locally.md) + + [Adding Packages to ConanCenter](how_to_add_packages.md) :point_left: Best place to learn how to contribute + [Errors from the conan-center hook (KB-Hxxx)](error_knowledge_base.md) - + [FAQs](faqs.md) - + [Community Resources](community_resources.md) - + [Review Guidelines](reviewing.md) + + [Review Process](review_process.md) + [Labels](labels.md) + + [Supported platforms and configurations](supported_platforms_and_configurations.md) + + [Consuming Recipes](consuming_recipes.md) :information_source: Learn how to limit the impact of recipe changes + + [Community Resources](community_resources.md) + [Preparing recipes for Conan 2.0](v2_migration.md) + + [FAQs](faqs.md) diff --git a/docs/consuming_recipes.md b/docs/consuming_recipes.md index 4e01f50335..ee80883fc7 100644 --- a/docs/consuming_recipes.md +++ b/docs/consuming_recipes.md @@ -32,7 +32,7 @@ There can be several causes if a recipe (a new revision) might stopped to work i This use case is covered by the [`required_conan_version`](https://docs.conan.io/en/latest/reference/conanfile/other.html?highlight=required_conan_version#requiring-a-conan-version-for-the-recipe) feature. It will substitute the syntax error by one nicer error provided by Conan client. - + To be sure that people using these new experimental features are using the required Conan version and testing the actual behavior of those features (feedback about them is very important to Conan). @@ -47,8 +47,8 @@ Here are a few choices: - [Running your own Conan Server](https://docs.conan.io/en/latest/uploading_packages/running_your_server.html) - great for local ad-hoc setups - [Cache recipes in your own ArtifactoryCE](https://docs.conan.io/en/latest/uploading_packages/using_artifactory.html) - recommended for production environments -Using your own ArtifactoryCE instance is easy. You can [deploy it on-premise](https://conan.io/downloads.html) or use a -[cloud provided solution](https://jfrog.com/community/start-free) for **free**. Your project should +Using your own ArtifactoryCE instance is easy. You can [deploy it on-premise](https://conan.io/downloads.html) or use a +[cloud provided solution](https://jfrog.com/community/start-free) for **free**. Your project should [use only this remote](https://docs.conan.io/en/latest/reference/commands/misc/remote.html?highlight=add%20new) and new recipe revisions are only pushed to your Artifactory after they have been validated in your project. @@ -59,7 +59,7 @@ The minimum solution, if still choosing to rely on ConanCenter directly, involve This feature needs to be enabled in Conan 1.x, see the [Activation Instructions](https://docs.conan.io/en/latest/versioning/revisions.html#how-to-activate-the-revisions) for details. - [Lockfiles](https://docs.conan.io/en/latest/versioning/lockfiles.html) can be created with the `conan lock create` and read with by adding `--lockfile=conan.lock` to `conan install` or `conan create` commands. See the [lockfile introduction](https://docs.conan.io/en/latest/versioning/lockfiles/introduction.html#) for more information. - + > **Warning** Please, be aware there are some known bugs related to lockfiles that are not being fixed in Conan v1.x - we are really excited for the 2.0 improvements to be widely used. Both of these give you better control and will allow you to choose when to upgrade your Conan client. diff --git a/docs/developing_recipes_locally.md b/docs/developing_recipes_locally.md new file mode 100644 index 0000000000..682ae2dd3e --- /dev/null +++ b/docs/developing_recipes_locally.md @@ -0,0 +1,214 @@ +# Developing Recipes Locally + +Before you can contribute any code changes, you'll need to make sure you are familiar with the Conan client and have an environment that is conducive to developing recipes. + +This file is intended to provide all the commands you need to run in order to be an expert ConanCenter contributor. + + +## Contents + + * [Clone your fork](#clone-your-fork) + * [Setup your environment](#setup-your-environment) + * [Installing the ConanCenter Hooks](#installing-the-conancenter-hooks) + * [Updating conan hooks on your machine](#updating-conan-hooks-on-your-machine) + * [Basic Commands](#basic-commands) + * [Try it yourself](#try-it-yourself) + * [Debugging Failed Builds](#debugging-failed-builds) + * [Running the Python Linters](#running-the-python-linters) + * [Testing the different `test__package`](#testing-the-different-test__package) + * [Testing more environments](#testing-more-environments) + * [Using Conan 2.0](#using-conan-20) + +## Clone your fork + +1. Follow the GitHub UI to [fork this repository](https://github.com/conan-io/conan-center-index/fork) +2. [Clone your fork](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) + +## Setup your environment + +1. Install a C++ development toolchain - ConanCenter's [build images](#testing-more-environments) are available +2. [Install the Conan client](https://docs.conan.io/en/latest/installation.html) - make sure to keep it up to date! +3. Install CMake - this is the only tool which is assumed to be present + [see FAQ](faqs.md#why-recipes-that-use-build-tools-like-cmake-that-have-packages-in-conan-center-do-not-use-it-as-a-build-require-by-default) for details. + +> **Note**: It's recommended to use a dedicated Python virtualenv when installing with `pip`. + +### Installing the ConanCenter Hooks + +The system will use the [conan-center hooks](https://github.com/conan-io/hooks) to perform some quality checks. You can install the hooks by running: + +```sh +conan config install https://github.com/conan-io/hooks.git -sf hooks -tf hooks +conan config set hooks.conan-center +``` + +The hooks will show error messages but the `conan create` won’t fail unless you export the environment variable `CONAN_HOOK_ERROR_LEVEL=40`. +All hooks checks will print a similar message: + +```txt +[HOOK - conan-center.py] post_source(): [LIBCXX MANAGEMENT (KB-H011)] OK +[HOOK - conan-center.py] post_package(): ERROR: [PACKAGE LICENSE] No package licenses found +``` + +#### Updating conan hooks on your machine + +The hooks are updated from time to time, so it's worth keeping your own copy of the hooks updated regularly. To do this, simply run: + +```sh +conan config install +``` + +## Basic Commands + +We recommend working from the `recipes/project` folder itself. You can learn about the [recipe file structure](how_to_add_packages.md#recipe-files-structure) to understand the folder and files located there. + +> **Note**: You can only change one recipe per pull request, and working from the [_recipe folder_](how_to_add_packages.md#the-recipe-folder-conanfilepy) will help prevent making a few mistakes. The default for this folder is `all`, follow the link above to learn more. + +The [entire workflow of a recipe](https://docs.conan.io/en/latest/developing_packages/package_dev_flow.html) can be execute with the [`conan create`](https://docs.conan.io/en/latest/reference/commands/creator/create.html). This should look like: + +* `conan create all/conanfile.py 0.0.0@ -pr:b=default -pr:h=default` + +ConanCenter also has a few [support settings and options](supported_platforms_and_configurations.md) which highly recommend to test. For example +`conan create all/conanfile.py 0.0.0@ -o project:shared=True -s build_type=Debug` is a easy way to test more configurations ensuring the package is correct. + +### Try it yourself + +For instance you can create packages for `fmt` in various supported configurations by running: + +```sh +cd recipes/fmt +conan create all/conanfile.py fmt/9.0.0@ -pr:b=default -pr:h=default +conan create all/conanfile.py fmt/9.0.0@ -o fmt:header_only=True -pr:b=default -pr:h=default +conan create all/conanfile.py fmt/9.0.0@ -s build_type=Debug -o fmt:shared=True -pr:b=default -pr:h=default +``` + +## Debugging Failed Builds + +Some common errors related to Conan can be found on [troubleshooting](https://docs.conan.io/en/latest/faq/troubleshooting.html) section. +For ConanCenter Hook errors, go to the [Error Knowledge Base](error_knowledge_base.md) page to know more about those. + +To test with the same environment, the [build images](supported_platforms_and_configurations.md#build-images) are available. +Instructions for using these images can be found in [Testing more environments](#testing-more-environments) section. + +In ConanCenterIndex, the most common failure point is upstream +build script that are tailored to their specific use cases. It's not uncommon to [patch build scripts](policy_patching.md#policy-about-patching) but make sure to read the [patch policy](policy_patching.md). You are encouraged to submit pull requests upstream. + +## Running the Python Linters + +Linters are always executed by Github actions to validate parts of your recipe, for instance, if it uses migrated Conan tools imports. + +It is possible to run the linter locally the same way it is being run [using Github actions](../.github/workflows/linter-conan-v2.yml) by: + +* (Recommended) Use a dedicated Python virtualenv. +* Ensure you have required tools installed: `conan` and `pylint` (better to uses fixed versions) + + ```sh + pip install conan~=1.0 pylint==2.14 + ``` + +* Set environment variable `PYTHONPATH` to the root of the repository + + ```sh + export PYTHONPATH=your/path/conan-center-index + ``` + +* Now you just need to execute the `pylint` commands: + + ```sh + # Lint a recipe: + pylint --rcfile=linter/pylintrc_recipe recipes/fmt/all/conanfile.py + + # Lint the test_package + pylint --rcfile=linter/pylintrc_testpackage recipes/fmt/all/test_package/conanfile.py + ``` + +## Testing the different `test_*_package` + +This can be selected when calling `conan create` or separately with `conan test` + +```sh +# By adding the `-tf` argument +conan create recipes/fmt/all/conanfile.py 9.0.0@ -tf test_v1_package/ -pr:b=default -pr:h=default +``` + +```sh +# Passing test package's conanfile directly (make sure to export first) +conan test recipes/fmt/all/test_v1_package/conanfile.py fmt/9.0.0@ -pr:h=default -pr:b=default +``` + +## Testing more environments + +This can be difficult for some platforms given virtualization support. + +For Windows and MacOS users, you can test the Linux build environments with the Docker build images. + +Assuming you've already tested it locally and it's been successfully exported to your cache, you can: + +1. Creating a new profile. + * You can also download them from CCI build summary +2. Build missing packages + +Example. + +```sh +docker run -v/Users/barbarian/.conan:/home/conan/.conan conanio/gcc8 bash -c "conan profile new --detect gcc8" +docker run -v/Users/barbarian/.conan:/home/conan/.conan conanio/gcc8 bash -c "conan install -pr gcc8 fmt/9.0.0@ --build missing" +``` + +> **Note**: If you are running on Mac M1, the follow Docker argument is required: `--platform=linux/amd64` + +## Using Conan 2.0 + +Everything you need to know about the methods, commands line, outputs can be found in the +[Conan 2.0 Migrations](https://docs.conan.io/en/latest/conan_v2.html) docs. + +This should be non-intrusive. Conan 2.0 by default has a different `CONAN_USER_HOME` location, which means that it has separate caches, profiles, and settings. +This will leave your Conan 1.0 setup completely intact when using Conan 2.0. + +> **Note**: There are substantial changes to the CLI so very few of the commands will remain the same. +> The new [Unified Command Pattern](https://docs.conan.io/en/latest/migrating_to_2.0/commands.html#unified-patterns-in-command-arguments), +> as an example, changes how settings and options are passed. + +### Installing Conan 2.0 beta + +Simply install Conan 2.0 with `pip install conan --upgrade --pre`. + +You can confirm the installation with: + +```sh +$ conan --version +Conan version 2.0.0-beta3 +$ conan config home +Current Conan home: /Users/barbarian/.conan2 +``` + +> **Note**: You will most likely see +> +> ```sh +> Initialized file: '/Users/barbarian/.conan2/settings.yml' +> Initialized file: '/Users/barbarian/.conan2/extensions/plugins/compatibility/compatibility.py' +> Initialized file: '/Users/barbarian/.conan2/extensions/plugins/compatibility/app_compat.py' +> Initialized file: '/Users/barbarian/.conan2/extensions/plugins/compatibility/cppstd_compat.py' +> Initialized file: '/Users/barbarian/.conan2/extensions/plugins/profile.py' +> ``` +> +> When running the client for the first time. + +You will need to setup profiles. This is one of the changes in 2.0. The default profile is now opt-in and no longer generated automatically. + +```sh +conan profile detect +``` + +> **Warning**: This is a best guess, you need to make sure it's correct. + +### Trying it out + +Try building an existing recipe. We'll repeat the 1.x example with `fmt` to build the same configurations: + +```sh +cd recipes/fmt +conan create all/conanfile.py --version 9.0.0 +conan create all/conanfile.py --version 9.0.0 -o fmt/9.0.0:header_only=True +conan create all/conanfile.py --version 9.0.0 -s build_type=Debug -o fmt/9.0.0:shared=True +``` diff --git a/docs/how_to_add_packages.md b/docs/how_to_add_packages.md index 6a48eaf220..a0457a78b8 100644 --- a/docs/how_to_add_packages.md +++ b/docs/how_to_add_packages.md @@ -1,8 +1,11 @@ # Adding Packages to ConanCenter -The [conan-center-index](https://github.com/conan-io/conan-center-index) (this repository) contains recipes for the remote [JFrog ConanCenter](https://conan.io/center/). -This remote is added by default to a clean installation of the Conan client. Recipes are contributed by opening pull requests as explained in the sections below. -When pull requests are merged, the CI will upload the generated packages to the [conancenter](https://conan.io/center/) remote. +ConanCenterIndex aims to provide the best quality packages of any open source project. +Any C/C++ project can be made available by contributing a "recipe". + +Getting started is easy. Try building an existing package with our [developing recipes](developing_recipes_locally.md) tutorial. +To deepen you understanding, start with the [How to provide a good recipe](#how-to-provide-a-good-recipe) section. +You can follow the three steps (:one: :two: :three:) described below! :tada: ## Contents @@ -27,9 +30,7 @@ When pull requests are merged, the CI will upload the generated packages to the * [Verifying Dependency Options](#verifying-dependency-options) * [Test the recipe locally](#test-the-recipe-locally) * [Hooks](#hooks) - * [Updating conan hooks on your machine](#updating-conan-hooks-on-your-machine) - * [Linters](#linters) - * [Debugging failed builds](#debugging-failed-builds) + * [Linters](#linters) ## Request access @@ -154,13 +155,14 @@ Also, **every `conanfile.py` should be accompanied by one or several folder to t All the packages in this repository need to be tested before they join ConanCenter. A `test_package` folder with its corresponding `conanfile.py` and a minimal project to test the package is strictly required. You can read about it in the - [Conan documentation](https://docs.conan.io/en/latest/creating_packages/getting_started.html). + Sometimes it is useful to test the package using different build systems (CMake, Autotools,...). Instead of adding complex logic to one `test_package/conanfile.py` file, it is better to add another `test_/conanfile.py` file with a minimal example for that build system. That way the examples will be short and easy to understand and maintain. In some other situations it could be useful to test different Conan generators -(`cmake_find_package`, `CMakeDeps`,...) using different folders and `conanfile.py` files ([see example](https://github.com/conan-io/conan-center-index/tree/master/recipes/fmt/all)). +(`cmake_find_package`, `CMakeDeps`,...) using different folders and `conanfile.py` files +([see example](https://github.com/conan-io/conan-center-index/tree/master/recipes/fmt/all)). When using more than one `test_` folder, create a different project for each of them to keep the content of the `conanfile.py` and the project files as simple as possible, without the need of extra logic to handle different scenarios. @@ -260,46 +262,17 @@ An example of this can be found in the [sdl_image recipe](https://github.com/con ### Hooks -The system will use the [conan-center hook](https://github.com/conan-io/hooks) to perform some quality checks. You can install the hook running: +The system will use the [conan-center hook](https://github.com/conan-io/hooks) to perform some quality checks. These are required for the +the CI to merge any pull request. -```sh -conan config install https://github.com/conan-io/hooks.git -sf hooks -tf hooks -conan config set hooks.conan-center -``` +Follow the [Developing Recipes Locally](developing_recipes_locally.md#installing-the-conancenter-hooks) guide for instructions. -The hook will show error messages but the `conan create` won’t fail unless you export the environment variable `CONAN_HOOK_ERROR_LEVEL=40`. -All hook checks will print a similar message: - -``` -[HOOK - conan-center.py] post_source(): [LIBCXX MANAGEMENT (KB-H011)] OK -[HOOK - conan-center.py] post_package(): ERROR: [PACKAGE LICENSE] No package licenses found -``` - -Call `conan create . lib/1.0@ -pr:b=default -pr:h=default` in the folder of the recipe using the profile you want to test. For instance: - -```sh -cd conan-center-index/recipes/boost/all -conan create conanfile.py boost/1.77.0@ -pr:b=default -pr:h=default -``` - -### Updating conan hooks on your machine - -The hooks are updated from time to time, so it's worth keeping your own copy of the hooks updated regularly. To do this: - -```sh -conan config install -``` +Go to the [Error Knowledge Base](error_knowledge_base.md) page to know more about Conan Center hook errors. +Some common errors related to Conan can be found on the [troubleshooting](https://docs.conan.io/en/latest/faq/troubleshooting.html) section. ### Linters Linters are always executed by Github actions to validate parts of your recipe, for instance, if it uses migrated Conan tools imports. All executed linters are documented in [linters.md](linters.md). -To understand how to run linters locally, read [V2 linter](v2_linter.md) documentation. - -## Debugging failed builds - -Go to the [Error Knowledge Base](error_knowledge_base.md) page to know more about Conan Center hook errors. - -Some common errors related to Conan can be found on [troubleshooting](https://docs.conan.io/en/latest/faq/troubleshooting.html) section. - -To test with the same enviroment, the [build images](supported_platforms_and_configurations.md#build-images) are available. +Check the [Developing Recipes](developing_recipes_locally.md#running-the-python-linters) page for running them locally. +Check the [Developing Recipes](developing_recipes_locally.md#running-the-python-linters) for running them locally. diff --git a/docs/labels.md b/docs/labels.md index 2646caeaa4..30b4d0a7ee 100644 --- a/docs/labels.md +++ b/docs/labels.md @@ -12,7 +12,11 @@ special meaning: * [Infrastructure](#infrastructure) * [Stale](#stale) * [Unexpected Error](#unexpected-error) - * [User-approval pending](#user-approval-pending) + * [User-approval pending](#user-approval-pending) + * [Library Request](#library-request) + * [Question](#question) + * [Upstream Update](#upstream-update) + * [conan.io/center](#conaniocenter) ## Bump dependencies @@ -62,3 +66,20 @@ will be changed to the status `Pending — This commit is being built` to signal 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. + +## Library Request + +Request a new package to be created. + +## Question + +Further information is requested. Usually these are for issue where help is needed to solve a specific issue. These are a great way +to look for advice or recommendation about making changes to recipes. + +## Upstream Update + +Request a bump of a new package version. + +## conan.io/center + +Issues and features related to Web UI. diff --git a/docs/linters.md b/docs/linters.md index e12d3847e2..76db1f45b3 100644 --- a/docs/linters.md +++ b/docs/linters.md @@ -1,37 +1,33 @@ -## Conan Center Index Linters +# ConanCenterIndex Linters Some linter configuration files are available in the folder [linter](../linter), which are executed by Github Actions to improve recipe quality. They consume python scripts which are executed to fit CCI rules. Those scripts use [astroid](https://github.com/PyCQA/astroid) and [pylint](https://pylint.pycqa.org/en/latest/) classes to parse Conan recipe files and manage their warnings and errors. -The pylint by itselt is not able to find Conan Center Index rules, so astroid is used to iterate over conanfiles content and +Pylint by itself is not able to find ConanCenterIndex rules, so astroid is used to iterate over conanfiles content and validate CCI conditions. Also, pylint uses [rcfile](https://pylint.pycqa.org/en/latest/user_guide/configuration/index.html) (a configuration file based on [toml](https://toml.io/en/) format) to configure plugins, warnings and errors which should be enabled or disabled. Also, the Github [code review](https://github.com/features/code-review) is integrated with the pylint output, parsed by [recipe_linter.json](../linter/recipe_linter.json), then presented to all users on the tab `Files changed`. -### Running Linters + +## Contents -Of course, you should run any linter locally, before pushing your code, read [Running the linter locally](v2_linter.md#running-the-linter-locally) for instructions. +## Running the linter locally +Check the [Developing Recipes](developing_recipes_locally.md#running-the-python-linters) page for details. -### Pylint configuration files +## Pylint configuration files -#### [Pylint Recipe](../linter/pylintrc_recipe) +- [Pylint Recipe](../linter/pylintrc_recipe): This `rcfile` lists plugins and rules to be executed over all recipes (not test package) and validate them. +- [Pylint Test Package Recipe](../linter/pylintrc_testpackage): This `rcfile` lists plugins and rules to be executed over all recipes in test package folders only: -This rcfile lists plugins and rules to be executed over all recipes (not test package) and validate them. - -#### [Pylint Test Package Recipe](../linter/pylintrc_testpackage) - -This rcfile lists plugins and rules to be executed over all recipes in test package folders only: - -### Linter Warning and Errors +## Linter Warning and Errors Here is the list of current warning and errors provided by pylint, when using CCI configuration. - -#### E9006 - conan-import-conanfile: ConanFile should be imported from conan +### E9006 - conan-import-conanfile: ConanFile should be imported from conan ```python from conans import ConanFile @@ -43,16 +39,7 @@ Should be replaced by: from conan import Conanfile ``` -#### E9004 - conan-package-name: Conan package names must be lower-case - -The package name is always lower-case, even when the upstream uses another format - -```python -def FoobarConanfile(ConanFile): - name = "foobar" -``` - -#### E9005 - conan-missing-name: Every conan recipe must contain the attribute name +### E9005 - conan-missing-name: Every conan recipe must contain the attribute name The attribute `name` is always expected. On the other hand, `version` should not be listed. @@ -61,17 +48,27 @@ def BazConanfile(ConanFile): name = "baz" ``` -#### E9007 - conan-test-no-name: Do not add name attribute in test package recipes +### E9004 - conan-package-name: Conan package names must be lower-case -The test package is not a package, thus, it should not have a name +The package name is always lower-case, even when the upstream uses another format + +```python +def FoobarConanfile(ConanFile): + name = "foobar" +``` + +### E9007 - conan-test-no-name: Do not add name attribute in test package recipes + +The test package is not a recipe, thus, it should not have a name ```python def TestPackageConanFile(ConanFile): name = "test_package" # Wrong! ``` -#### E9008 - conan-import-errors: Deprecated imports should be replaced by new imports. Read [v2_linter](v2_linter.md) +### E9008 - conan-import-errors: Deprecated imports should be replaced by new imports +Read [v2_linter](v2_linter.md) for a list of mappings of v1 to v2. Regular imports from `conans.tools` are now updated: ```python @@ -81,7 +78,7 @@ from conans import tools tools.rmdir(os.path.join(self.package_folder, "shared")) ``` -Should be replaced by specilized tools, prepared for Conan 2.0 +Should be replaced by specialized tools, prepared for Conan 2.0 ```python from conan.tools.files import rmdir @@ -90,7 +87,7 @@ from conan.tools.files import rmdir rmdir(self, os.path.join(self.package_folder, "shared")) ``` -#### E9009 - conan-import-error-conanexception: conans.errors is deprecated and conan.errors should be used instead +### E9009 - conan-import-error-conanexception: conans.errors is deprecated and conan.errors should be used instead ```python from conans.errors import ConanException @@ -104,8 +101,7 @@ from conan.errors import ConanException Only the namespace `conans` has been replaced by `conan`. - -#### E9010 - conan-import-error-conaninvalidconfiguration: conans.errors is deprecated and conan.errors should be used instead +### E9010 - conan-import-error-conaninvalidconfiguration: conans.errors is deprecated and conan.errors should be used instead ```python from conans.errors import ConanInvalidConfiguration @@ -119,11 +115,9 @@ from conan.errors import ConanInvalidConfiguration Only the namespace `conans` has been replaced by `conan`. -#### E9011 - conan-import-tools: Importing conan.tools or conan.tools.xxx.zzz.yyy should be considered as private +### E9011 - conan-import-tools: Importing conan.tools or conan.tools.xxx.zzz.yyy should be considered as private Documented on [conanfile.tools](https://docs.conan.io/en/latest/reference/conanfile/tools.html): - - It's not allowed to use `tools.xxx` directly: ```python diff --git a/docs/review_process.md b/docs/review_process.md index d2b04f728b..e29387f248 100644 --- a/docs/review_process.md +++ b/docs/review_process.md @@ -49,13 +49,8 @@ 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, -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. -Sometimes it's necessary to restart the build several times. -If an `Unexpected error` persists, tag [@jgsogo](https://github.com/jgsogo) and [@danimtb](https://github.com/danimtb) asking for the help with CI. -Alternatively, just [open a new issue](https://github.com/conan-io/conan-center-index/issues/new/choose). +To learn more, checkout the [label definition](labels.md#unexpected-error). ## Avoiding conflicts diff --git a/docs/v2_linter.md b/docs/v2_linter.md index 89a67d715d..bf0e494551 100644 --- a/docs/v2_linter.md +++ b/docs/v2_linter.md @@ -21,6 +21,10 @@ if perfectly valid in Conan v1, the recipe might fail here because it is not v2- Here you can find some examples of the extra rules we are adding: +## Running the linter locally + +Check the [Developing Recipes](developing_recipes_locally.md#running-the-python-linters) for details. + ## Import ConanFile from `conan` The module `conans` is deprecated in Conan v2. Now all the imports should be done from @@ -65,30 +69,3 @@ Here is a list of different imports and their new equivalent (note that the inte | conans.errors.ConanException | [conan.errors.ConanException](https://docs.conan.io/en/latest/migrating_to_2.0/recipes.html#migrating-the-recipes) | 1.47.0 | --- - -## Running the linter locally - -It is possible to run the linter locally the same way it is being run [using Github actions](../.github/workflows/linter-conan-v2.yml): - - * (Recommended) Use a dedicated Python virtualenv. - * Ensure you have required tools installed: `conan` and `pylint` (better to uses fixed versions) - - ``` - pip install conan~=1.0 pylint==2.14 - ``` - - * Set environment variable `PYTHONPATH` to the root of the repository - - ``` - export PYTHONPATH=your/path/conan-center-index - ``` - - * Now you just need to execute the `pylint` commands: - - ``` - # Lint a recipe: - pylint --rcfile=linter/pylintrc_recipe recipes/boost/all/conanfile.py - - # Lint the test_package - pylint --rcfile=linter/pylintrc_testpackage recipes/boost/all/test_package/conanfile.py - ```