conda-forge.github.io

conda-forge.github.io copied to clipboard

• [x] I read the conda-forge documentation and could not find the solution for my problem there.

Issue: https://conda-forge.org/docs/user/ci-skeleton.html#using-conda-smithy-to-manage-your-ci Using conda-smithy to manage your CI section is there in USER Docs. I am a little confused as to why a new comer or a user would be concerned with CI management of the package they want to install. Maybe I am not totally aware of the workflow, so I'm opening this issue to get the opinions of all. Shouldn't it be under Maintainers docs?

This section is not about using the conda package but about something totally different. Let's leave it where it is.

We just had a new user run into this webpage and use it to try and re-render: https://github.com/conda-forge/conda-smithy/issues/1842#issuecomment-2101647788

Can completely understand where they are coming from as the "User Documentation" has a lot of info for helping new users. For example "A brief Introduction", "Becoming Involved", "How to get help", "FAQ", etc.. So it might be reasonable to think "Using conda-smithy to manage your CI" being in "User Documentation" is intended for new conda-forge users

However "Using conda-smithy to manage your CI" is talking about how to configure feedstock external to conda-forge, which is pretty advanced material. It is kind of jarring to have this next to intro material. Tbh am surprised this hasn't caused more problems for new users

Was about to file a new issue for this, when I found this old one. Think we should reconsider this page's location

cc @jaimergp (in case this is something you have thoughts on as well)

Can completely understand where they are coming from as the "User Documentation" has a lot of info for helping new users. For example "A brief Introduction", "Becoming Involved", "How to get help", "FAQ", etc.. So it might be reasonable to think "Using conda-smithy to manage your CI" being in "User Documentation" is intended for new conda-forge users

I agree, but my view is slightly different than that. I'm a maintainer of multiple conda-forge recipes for more than 5 years, but I generally only interact with conda-smithy when I'm reviewing a new release PR (and so I am new to viewing it as anything outside of arguments to the right incantations to talk with a bot (conda-forge-admin)). The "problem" in https://github.com/conda-forge/conda-smithy/issues/1842#issuecomment-2101651063 was that when asked to certify that

Solution to issue cannot be found in the documentation.

there is no "conda-smithy docs". There is the (very nice! and terribly huge!) conda-forge docs, and if you search the docs for "conda-smithy"

the most reasonable thing for controlling conda-smithy via GitHub in the search results is the "Using conda-smithy to manage your CI" hit, whereas the actual information is found under https://conda-forge.org/docs/maintainer/infrastructure/#conda-forge-admin-please-rerender, which doesn't appear in the "conda-smithy" search results (unsurprisingly) as there is no mention of conda-smithy in the answer.

When searching the docs I'm not making a decision to look between the "user" and "maintainer" docs, I'm just searching for anything that seems reasonable and not paying much attention to the section it lives under. I've always found the distinction a bit weird as the "user" docs are so short and seem like they should be their own thing located somewhere else, which further supports the idea that the conda-smithy docs should get migrated to the "maintainer" sections.

So given that last statement, it would also probably help to have on both the user docs and maintainer docs top level pages a "Who is this for" summary, to help steer people a bit. I think most people coming to the docs aren't sure what a "user" is (in my view from reading the docs, it is someone who uses a conda family tool and just wants to install packages from conda-forge) and what a "maintainer" is (in my view from reading the docs, it is someone like me who is distributing their tools through packaging on conda-forge).

(Aside: Though with the "maintainer" docs there probably could be some more modularity, I find that for any getting any non-trivial (aka, something beyond grayskull pypi generated) recipe to build I need to spend a fair amount of time Ctrl+f-ing my way through the Knowledge Base and reading the conda-build metadata docs.)

edit: Original response wasn't clear and didn't get my view across, so revised hopefully for clarity.

Thanks for the excellent feedback. Hopefully we can tackle this as part of https://github.com/conda-forge/conda-forge.github.io/issues/2164. I agree with your points.

conda-smithy has some docs in its README, but not sure if that's enough.

Hopefully we can tackle this as part of https://github.com/conda-forge/conda-forge.github.io/issues/2164. I agree with your points.

Thanks and that's great to see the work being done on the Issue. :+1:

conda-smithy has some docs in its README, but not sure if that's enough.

Here (Issue https://github.com/conda-forge/conda-smithy/issues/1842) I think the problem was that I only have micromamba and pixi installed, and so no base conda environment, which I believe is required for the conda smithy rerender command to work. I don't think that caveat shows up in the README.