Skip to content

Commit

Permalink
Apply suggestions from code review
Browse files Browse the repository at this point in the history
Co-authored-by: SSE4 <tomskside@gmail.com>
  • Loading branch information
Chris Mc and SSE4 authored Jan 3, 2023
1 parent 73ea163 commit 7b00484
Show file tree
Hide file tree
Showing 4 changed files with 26 additions and 26 deletions.
16 changes: 8 additions & 8 deletions docs/adding_packages/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,11 +45,11 @@ The process will be precisely like for newcomers.
## :two: Creating a package

Once you've successfully built an existing recipe following [developing recipes](../developing_recipes_locally.md) tutorial.
You are set to being.
You are set to being adding a new package.

Make sure you have:

* Fork and then clone the [conan-center-index](https://github.com/conan-io/conan-center-index) git repository.
* Forked and then cloned the [conan-center-index](https://github.com/conan-io/conan-center-index) git repository.
* Make sure you are using a recent [Conan client](https://conan.io/downloads) version, as recipes improve by introducing features of the newer Conan releases.

The easiest way to start is copying a template from our [`package_templates/`](../package_templates) folder to the [`recipes/`](../../recipes/) folder.
Expand All @@ -59,14 +59,14 @@ to find more information.
Quickly, there's a few items to look at:

* Add _only_ the latest version in the [`config.yml`](folders_and_files.md#configyml) and [`conandata.yml`](folders_and_files.md#conandatayml)
* Make sure to update the [`ConanFile` attributes](conanfile_attributes.md) like `license`, `description`, ect...
* Make sure to update the [`ConanFile` attributes](conanfile_attributes.md) like `license`, `description`, etc...

In ConanCenter, our belief is recipes should always match upstream, in other words, what the original author(s) intended.

* Options should [follow these recommendations](conanfile_attributes.md#options) as well as match the default value used by the upstream project.
* [Package information](build_and_package.md), libraries, components should match as well. This includes exposing supported build system names.

Where dependencies are involved, there's no shortcuts, inspect the upstream's build scripts for how they usually consume them. Pick the Conan
Where dependencies are involved, there's no shortcuts, inspect the upstream's build scripts for how they are usually consumed. Pick the Conan
generator that matches. The most common example is CMake's `find_package` that can be satisfied by Conan's
[`CMakeDeps`](https://docs.conan.io/en/latest/reference/conanfile/tools/cmake/cmakedeps.html) generator. There are a few
things to be cautious about, many projects like to "vendor" other projects within them. This can be files checked into the repository or
Expand All @@ -81,12 +81,12 @@ how or when a function is used in other recipes.

> **Note**: Conan features change over time and our best practices evolve so some minor details may be out of date due to the vast number of recipes.
More often then not, ConanCenter recipes are built in more configuration then the upstream project. This means some edge cases need minor tweaks.
We **strongly encourage** everyone to contribute back to the upstream project. This reduce the burden of re-applying patches and overall makes the
More often than not, ConanCenter recipes are built in more configuration than the upstream project. This means some edge cases need minor tweaks.
We **strongly encourage** everyone to contribute back to the upstream project. This reduces the burden of re-applying patches and overall makes the
the code more accessible.

Read the docs! The [FAQs](../faqs.md) are a great place to find short answers.
The documents in this folder are written to explain each folder, file, method and attribute and specific conventions.
The documents in this folder are written to explain each folder, file, method, and attribute.

1. [Folders and Files](folders_and_files.md)
2. [Sources and Patches](sources_and_patches.md)
Expand Down Expand Up @@ -125,7 +125,7 @@ For a C++ library, the system is currently generating more than 100 binary packa
> **Note**: This not a testing service, it is a binary building service for **released** packages. Unit tests shouldn't be built nor run in recipes by default, see the [FAQs](../faqs.md#why-conancenter-does-not-build-and-execute-tests-in-recipes) for more. Before submitting a pull request, please ensure that it works locally for some configurations.
* The CI bot will start a new build only [after the author is approved](#one-request-access). Your PR may be reviewed in the mean time, but is not guaranteed.
* The CI system will also report errors and build logs by creating a comment in the pull-request, The message will include links to the logs for inspecting.
* The CI system will also report errors and build logs by creating a comment in the pull-request, the message will include links to the logs for inspecting.
* The Actions are used to lint and ensure the latest conventions are being used. You'll see comments from bots letting you know.

Packages generated and uploaded by this build service do not include any _user_ or _channel_ (we generally recommend using `@user/channel` for private package
Expand Down
8 changes: 4 additions & 4 deletions docs/adding_packages/conanfile_attributes.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ or are known by ConanCenter's build service and have special meaning.

## Attributes

There's are a [key features](https://docs.conan.io/en/latest/reference/conanfile/attributes.html) which allow the Conan client to understand,
These are a [key feature](https://docs.conan.io/en/latest/reference/conanfile/attributes.html) which allow the Conan client to understand,
identify, and expose recipes and which project they expose.

In ConanCenter, there are a few conventions that need to be respected to ensure recipes can be discovered there `conan search` command
Expand All @@ -36,8 +36,8 @@ Please see the FAQs for:

### Version

ConanCenter is geared towards quickly added new release, the build service always pass the version it it currently building to the recipe.
The `version` attribute MUST NOT be added to any recipe - with except to "system packages".
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

Expand All @@ -51,7 +51,7 @@ The mandatory license attribute of each recipe **should** be a [SPDX license](ht

Where the SPDX guidelines do not apply, packages should do the following:

* When no license is provided or it's under the ["public domain"](https://fairuse.stanford.edu/overview/public-domain/welcome/) - these are not a license by itself. Thus, we have [equivalent licenses](https://en.wikipedia.org/wiki/Public-domain-equivalent_license) that should be used instead. If a project fall under these criteria it should be identified as the [Unlicense](https://spdx.org/licenses/Unlicense) license.
* When no license is provided or it's under the ["public domain"](https://fairuse.stanford.edu/overview/public-domain/welcome/) - these are not a license by itself. Thus, we have [equivalent licenses](https://en.wikipedia.org/wiki/Public-domain-equivalent_license) that should be used instead. If a project falls under these criteria it should be identified as the [Unlicense](https://spdx.org/licenses/Unlicense) license.
* When a custom (e.g. project specific) license is given, the value should be set to `LicenseRef-` as a prefix, followed by the name of the file which contains the custom license. See [this example](https://github.com/conan-io/conan-center-index/blob/e604534bbe0ef56bdb1f8513b83404eff02aebc8/recipes/fft/all/conanfile.py#L8). For more details, [read this conversation](https://github.com/conan-io/conan-center-index/pull/4928/files#r596216206).


Expand Down
26 changes: 13 additions & 13 deletions docs/adding_packages/folders_and_files.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Folder and Files Structure

ConanCenterIndex has a specific structure for it's recipes, this allows the [build service](../README.md#the-build-service)
ConanCenterIndex has a specific structure for its recipes, this allows the [build service](../README.md#the-build-service)
to work most efficiently.

<!-- toc -->
Expand Down Expand Up @@ -58,13 +58,13 @@ versions:
folder: all
```
This simply files has the following format:
This simple file has the following format:
* `versions` is a top level dictionary, containing a list of known versions.
* `folder` is a string entry providing the name of the folder, relative to the current directory where the `conanfile.py` that
can package that given folder.

If it's no possible to maintain one recipe for all version, older version maybe moved to a separate folder.
If it's not possible to maintain one recipe for all version, older version maybe moved to a separate folder.

```yml
versions:
Expand All @@ -83,12 +83,12 @@ This contains every needed to build packages.
#### `conandata.yml`

This file lists **all the sources** that are needed to build the package. The most common examples are
source code, build scripts, license files .
source code, build scripts, license files.

The file is organized into two sections, `"sources"` and `"patches"`, each one of them contains the files that are required
for each version of the library. Resources which need to be downloaded are listed under `"source"` should include a checksum
to validate that they do not change. This helps to ensure the build are reproducible at a later point in time. Often
modifications are requires for a variety of reasons, which ones are associated to which version are listed under the `"patches"`.
to validate that they do not change. This helps to ensure the build is reproducible at a later point in time. Often
modifications are required for a variety of reasons, which ones are associated to which version are listed under the `"patches"`.

```yml
sources:
Expand All @@ -114,7 +114,7 @@ def source(self):
```

See the [Export Patches](sources_and_patches.md#exporting-patches) and [Applying Patches](sources_and_patches.md#applying-patches)
for more use case and examples.
for more use cases and examples.

#### `conanfile.py`

Expand All @@ -125,7 +125,7 @@ It's the single most important part of writing a package. Every `conanfile.py` s
Each recipe should derive the `ConanFile` class and implement key attributes and methods.

* Basic attributes and conversions can be found in [`ConanFile` attributes](conanfile_attributes.md)
* Some of the key methods are outline in this document and will link to more details
* Some of the key methods are outlined in this document and will link to more details

```python
from conan import ConanFile
Expand All @@ -136,17 +136,17 @@ class FmtConan(ConanFile):
# ...
```

When a package needs other packages those are can be include with the `requirements()` methods.
When a package needs other packages those can be include with the `requirements()` method.

```python
def requirements(self):
self.require("fmt/9.0.0")
```

For more information see the [Dependencies](dependencies.md) documentation for more use cases.
For more information see the [Dependencies](dependencies.md) documentation.

For compiled libraries, the `build()` method is used along side the [build helpers](https://docs.conan.io/en/latest/reference/build_helpers.html).
List allows you to use the official build script from a project, see [build and package](build_and_package.md) instructions.
This allows you to use the official build script from a project, see [build and package](build_and_package.md) instructions.

```python
def build(self):
Expand All @@ -155,7 +155,7 @@ List allows you to use the official build script from a project, see [build and
cmake.build()
```

Most project's with build scripts support installing the important files. Avoid installing documentation or examples.
Most of the projects with build scripts support installing the important files. Avoid installing documentation or examples.

```python
def package(self):
Expand Down Expand Up @@ -185,7 +185,7 @@ The goal for the test package is to make sure the
* libraries are available to link against
* components are correctly exposed

> **Note** It's required to verify that the old generator are not broken. You can do so by using the pattern, see
> **Note** It's required to verify that the old generators are not broken. You can do so by using the pattern, see
> [KB-H073](../error_knowledge_base.md#kb-h078) for details.

Remember that the `test_<package>` recipes should **test the package configuration that has just been generated** for the
Expand Down
2 changes: 1 addition & 1 deletion docs/faqs.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ Unless they are a general and extended utility in recipes (in which case, we sho

## What version should packages use for libraries without official releases?

This happens for a number of reasons, some have a "live on main" others are less maintained but still merge pull requests.
This happens for a number of reasons, some projects have a "live on main" others are less maintained but still merge pull requests.
Read about the [ConanCenter specific version format](adding_packages/conanfile_attributes.md#conancenter-specific-releases-format) for more information.

## Is the Jenkins orchestration library publicly available?
Expand Down

0 comments on commit 7b00484

Please sign in to comment.