docs: split out files and folders and the last few attributes #15004

prince-chrismc · 2022-12-29T20:07:08Z

Docs!

closes #13673 This is the last installment, I am very certain there is more work but it should be hopefully easier for contributors to learn where they should start and give some basic guidance as to where to look for information.
This also helps outline what to expect which has been a pain point recently 🤞 .

I am sure there will be a follow up to refine the language but this should give a good starting pointing.

…method

Co-authored-by: prince-chrismc <prince-chrismc@users.noreply.github.com>

uilianries

LGTM

docs/adding_packages/README.md

SSE4 · 2023-01-03T17:16:27Z

docs/adding_packages/README.md


-A detailed breakdown of all the fields can be found in [conandata_yml_format.md](conandata_yml_format.md). We **strongly** encourage adding the [patch fields](conandata_yml_format.md#patches-fields) to help track where patches come from and what issue they solve.
+* 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.


what are supported build system names? I think it's first time this term mentioned, but I don't have an idea what does it mean... 🤔

docs/adding_packages/README.md

docs/adding_packages/conanfile_attributes.md

docs/adding_packages/folders_and_files.md

SSE4 · 2023-01-03T17:42:26Z

docs/adding_packages/folders_and_files.md

+* 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


also, what is the old generator?

docs/faqs.md

docs/adding_packages/README.md

SSE4 · 2023-01-03T17:50:49Z

some generic advises on wording:

avoid subjective wording like great, fantastic, outstanding and so on
avoid referring to entities with vague pronouns (it, they, that, this, these and so on), especially, when talking about multiple entities in parallel
avoid future tenses, I would use present for instructions (otherwise, it's not clear if things already exist at the moment of publishing). same for can, could, and similar.

Co-authored-by: SSE4 <tomskside@gmail.com>

prince-chrismc · 2023-01-03T19:47:24Z

Thanks for the detailed review as always, some of the suggestions were to expressions and did not make sense, some I needed to tweak but overall super helpful. ❤️

I hate dry docs and I will always try to add adjectives to make them seem more engaging. This is a tutorial not a technical reference. The goal is to provide enough information for contributors to start, not the end-all-be-all of resources for everyone so it's acceptable for there to be some open questions for them to look up information.

This is a starting pointing for people to write recipes, not a technical reference that should be left to the main docs.conan.io website 😄

It's important to avoid writing absolute statements instead we are trying to provide guidance and not artificially limit ourselves by overly tight languge.

There is already way to much docs here that should be in the main docs and one of my future steps will be to move them after the 2.0 launch settles 🤞

franramirez688

Great job!

franramirez688 · 2023-01-25T08:22:22Z

docs/adding_packages/README.md


-Inside the `conanfile.py` recipe, this data is available in a `self.conan_data` attribute that can be used as follows:
+Where dependencies are involved, there's no shortcuts, inspect the upstream's build scripts for how they are usually consumed. Pick the Conan


Suggested change

Where dependencies are involved, there's no shortcuts, inspect the upstream's build scripts for how they are usually consumed. Pick the Conan

Where dependencies are involved, there are no shortcuts, inspect the upstream's build scripts for how they are usually consumed. Pick the Conan

franramirez688 · 2023-01-25T08:23:46Z

docs/adding_packages/README.md

+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


Suggested change

things to be cautious about, many projects like to "vendor" other projects within them. This can be files checked into the repository or

things to be cautious about, many projects like to "vendor" other projects within them. These can be files checked into the repository or

franramirez688 · 2023-01-25T08:26:56Z

docs/adding_packages/conanfile_attributes.md

-For `conan create` the order is listed [here](https://docs.conan.io/en/latest/reference/commands/creator/create.html#methods-execution-order)
-test packages recipes should append the following methods:
+In ConanCenter, there are a few conventions that need to be respected to ensure recipes can be discovered there `conan search` command
+of through the web UI. Many of which are enforces with the [hooks](../error_knowledge_base.md).


Suggested change

of through the web UI. Many of which are enforces with the [hooks](../error_knowledge_base.md).

through the web UI. Many of these are enforced with the [hooks](../error_knowledge_base.md).

franramirez688 · 2023-01-25T08:30:40Z

docs/adding_packages/conanfile_attributes.md


-For `conan create` the order is listed [here](https://docs.conan.io/en/latest/reference/commands/creator/create.html#methods-execution-order)
-test packages recipes should append the following methods:
+In ConanCenter, there are a few conventions that need to be respected to ensure recipes can be discovered there `conan search` command


Suggested change

In ConanCenter, there are a few conventions that need to be respected to ensure recipes can be discovered there `conan search` command

In ConanCenter, there are a few conventions that need to be respected to ensure recipes can be discovered with the `conan search` command

franramirez688 · 2023-01-25T08:32:10Z

docs/adding_packages/conanfile_attributes.md

+
+#### 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>`.


Suggested change

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 that do not match the original library's official releases. This format includes the "datestamp" corresponding to the date of a commit: `cci.<YEAR MONTH DAY>`.

franramirez688 · 2023-01-25T08:33:27Z

docs/adding_packages/conanfile_attributes.md

+
+### Version
+
+ConanCenter is geared towards quickly added new release, the build service always pass the version it is currently building to the recipe.


Suggested change

ConanCenter is geared towards quickly added new release, the build service always pass the version it is currently building to the recipe.

ConanCenter is geared towards quickly adding a new release, the build service always passes the version it is currently building to the recipe.

franramirez688 · 2023-01-25T08:33:57Z

docs/adding_packages/conanfile_attributes.md

+### 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".


Suggested change

The `version` attribute MUST NOT be added to any recipe - with exception to "system packages".

The `version` attribute MUST NOT be added to any recipe - with the exception of "system packages".

franramirez688 · 2023-01-25T08:37:12Z

docs/adding_packages/conanfile_attributes.md


 The mandatory license attribute of each recipe **should** be a [SPDX license](https://spdx.org/licenses/) [short Identifiers](https://spdx.dev/ids/) when applicable.

 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 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).
+* 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.


Suggested change

* 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 no license is provided or it's under the ["public domain"](https://fairuse.stanford.edu/overview/public-domain/welcome/) - this is 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.

franramirez688 · 2023-01-25T08:48:08Z

docs/adding_packages/conanfile_attributes.md


+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


Suggested change

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

The order above resembles the execution order of methods on CI. Therefore, for instance, `build` is always executed before the `package` method, so `build` should appear before the

…ttributes * docs: organize "adding packages" by files and methods * typo * modernize the main readme + second pass to improve language * [docs] Regenerate tables of contents Co-authored-by: prince-chrismc <prince-chrismc@users.noreply.github.com> * update the folder and files to match other recent changes * Apply suggestions from code review Co-authored-by: SSE4 <tomskside@gmail.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: prince-chrismc <prince-chrismc@users.noreply.github.com> Co-authored-by: SSE4 <tomskside@gmail.com>

Christopher McArthur and others added 7 commits November 29, 2022 13:10

docs: organize "adding packages" by files and methods

3e3ee93

Merge remote-tracking branch 'upstream/master' into docs/seperate-by-…

dd8eab1

…method

Merge remote-tracking branch 'upstream/master' into docs/seperate-by-…

071e4ea

…method

typo

37f4b01

modernize the main readme + second pass to improve language

d41e8d4

[docs] Regenerate tables of contents

0ce8440

Co-authored-by: prince-chrismc <prince-chrismc@users.noreply.github.com>

update the folder and files to match other recent changes

73ea163

conan-center-bot added the Docs label Dec 29, 2022

github-actions bot mentioned this pull request Dec 29, 2022

Pull Requests Ready to be Reviewed prince-chrismc/conan-center-index-pending-review#1

Open

prince-chrismc mentioned this pull request Dec 29, 2022

Docs: Improved Structure for "adding packages" to help contributors find information #13673

Closed

10 tasks

uilianries previously approved these changes Jan 2, 2023

View reviewed changes