Rework glossary (#2087)

* rework glossary * Bring #1363 Co-authored-by: angeloobeta <[email protected]> * Bring #1395 Co-authored-by: Aaishpra <[email protected]> * These are not acronyms * adjust editURL so it works with new pages introduced by PRs * dump context (debug) * use event payload * extend http codes considered valid --------- Co-authored-by: angeloobeta <[email protected]> Co-authored-by: Aaishpra <[email protected]>
conda-forge · Feb 28, 2024 · 451f1c1 · 451f1c1
1 parent 3fc4e0d
commit 451f1c1
Show file tree

Hide file tree

Showing 14 changed files with 116 additions and 90 deletions.
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -31,6 +31,7 @@ jobs:
           source ./.ci_scripts/update_docs
         env:
           GHREF: ${{ github.ref }}
+          GHREPO: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
 
       - name: deploy
         if: github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
@@ -50,6 +51,7 @@ jobs:
           args: >
             --no-progress
             --base "$(pwd)/build"
+            --accept 100..399,401,403,429
             --exclude 'https://polys.me/?$'
             --exclude 'https://kb43fqob7u-dsn.algolia.net/'
             --exclude '.*/404.html/'

diff --git a/docs/glossary.md b/docs/glossary.md
@@ -0,0 +1,80 @@
+---
+title: 'Glossary'
+sidebar_position: 27
+---
+
+<a id="miscellaneous"></a>
+
+<a id="misc-glossary"></a>
+
+<a id="glossary"></a>
+
+# Glossary
+
+<a id="term-ABI"></a>
+
+## ABI
+
+**A**pplication **B**inary **I**nterface. ABI is a document that comprehensively defines the binary system interface between applications and the operating system on which they run. [Learn More](https://en.wikipedia.org/wiki/Application_binary_interface).
+
+<a id="term-CDT"></a>
+
+## CDT
+
+**C**ore **D**ependency **T**ree. Core Dependency Tree packages take care of the dependencies which are so close to the system that they are not packaged with conda-forge. A CDT package consists of repackaged CentOS binaries from the appropriate version, either 6 or 7 depending on user choice and platform. [Learn more](maintainer/knowledge_base.md#cdt-packages).
+
+## CLI
+
+**C**ommand **L**ine **I**nterface. A program in which commands are entered as text, one line at a time, for a computer to execute. This is done in the Miniforge Prompt in Windows, and in a terminal in macOS and Linux. `conda` is executed in a CLI. [Learn More](https://en.wikipedia.org/wiki/Command-line_interface).
+
+<a id="term-CI"></a>
+
+## CI
+
+**C**ontinuous **I**ntegration. Continuous integration is the practice of automating the integration of code changes from multiple contributors into a single software project. [Learn More](https://en.wikipedia.org/wiki/Continuous_integration).
+
+<a id="term-CFEP"></a>
+
+## CFEP
+
+**C**onda **F**orge **E**nhancement **P**roposal. A CFEP is a document which outlines a suggested change to how the conda-forge project operates, from a technical standpoint as well as to address social topics such as governance and expected conduct. [Learn More](https://github.com/conda-forge/cfep/blob/main/cfep-01.md/).
+
+<a id="term-Conda-channel"></a>
+
+## Conda channel
+
+Conda channels are the locations where packages are stored. They serve as the base for hosting and managing packages. `conda-forge` is one example of a conda channel. [Learn More](https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/channels.html).
+
+<a id="term-Conda-package"></a>
+
+## Conda package
+
+A conda package is a `.tar.bz2` or `.conda` archive that contains libraries, executable programs, data files and other components, as well as metadata under the `info/` directory. Its contents are unpacked in the installation prefix. [Learn More](https://en.wikipedia.org/wiki/Conda_(package_manager)).
+
+<a id="term-CRAN"></a>
+
+## CRAN
+
+**C**omprehensive **R** **A**rchive **N**etwork. CRAN is a network of FTP and web servers around the world that store identical, up-to-date, versions of code and documentation for R. [Learn More](https://cran.r-project.org/).
+
+<a id="term-Environment"></a>
+
+## Environment
+
+An environment is a tool that helps to keep dependencies required by different projects separate by creating isolated spaces where these dependencies are installed. [Learn More](https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/environments.html).
+
+<a id="term-ICU"></a>
+
+## ICU
+
+**I**nternational **C**omponents for **U**nicode. ICU is an open-source project of mature C/C++ and Java libraries for Unicode support, software internationalization, and software globalization. [Learn More](https://icu.unicode.org/).
+
+<a id="term-PR"></a>
+
+## PR
+
+**P**ull **R**equest. Pull Request is a workflow method to submit contributions to an open development project in which the developer asks for changes committed to an external repository to be considered for inclusion in a project's main repository. [Learn More](https://help.github.com/articles/about-pull-requests/).
+
+## Recipe
+
+A recipe is a collection of files required to build a conda package. This includes, at minimum, a [`meta.yaml`](maintainer/adding_pkgs.md#the-recipe-meta-yaml) file, but can also include license files, patches, build scripts, test scripts etc. [Learn More](https://docs.conda.io/projects/conda-build/en/stable/resources/define-metadata.html).
diff --git a/docs/index.md b/docs/index.md
@@ -39,5 +39,5 @@ Chances are we have already packaged it for you. You can [search](https://anacon
 * [User Documentation](user/index.mdx)
 * [Maintainer Documentation](maintainer/index.mdx)
 * [Organisation Documentation](orga/index.mdx)
-* [Miscellaneous](misc/index.md)
+* [Miscellaneous](glossary.md)
 * [Contracting Information](contracting/index.md)
diff --git a/docs/maintainer/adding_pkgs.md b/docs/maintainer/adding_pkgs.md
@@ -131,7 +131,7 @@ Once you finished your PR, all you have to do is wait for feedback from our revi
 
 The review team will assist you by pointing out improvements and answering questions. Once the package is ready, the reviewers will approve and merge your pull request.
 
-After merging the [PR](../misc/index.md#term-PR), our [CI](../misc/index.md#term-CI) infrastructure will build the package and make it available in the conda-channel.
+After merging the [PR](../glossary.md#term-PR), our [CI](../glossary.md#term-CI) infrastructure will build the package and make it available in the conda-channel.
 
 :::note
 
@@ -145,10 +145,10 @@ If you have questions or have not heard back for a while, you can notify us by i
 
 ## Post staging process
 
-* After the PR is merged, our [CI](../misc/index.md#term-CI) services will create a new git repo automatically. For example, the recipe for a package named `pydstool` will be moved to a new repository [https://github.com/conda-forge/pydstool-feedstock](https://github.com/conda-forge/pydstool-feedstock). This process is automated through a CI job on the `conda-forge/staged-recipes` repo. It sometimes fails due to API rate limits and will automatically retry itself. If your feedstock has not been created after a day or so, please get in touch with the `conda-forge/core` team for help.
+* After the PR is merged, our [CI](../glossary.md#term-CI) services will create a new git repo automatically. For example, the recipe for a package named `pydstool` will be moved to a new repository [https://github.com/conda-forge/pydstool-feedstock](https://github.com/conda-forge/pydstool-feedstock). This process is automated through a CI job on the `conda-forge/staged-recipes` repo. It sometimes fails due to API rate limits and will automatically retry itself. If your feedstock has not been created after a day or so, please get in touch with the `conda-forge/core` team for help.
 * CI services will be enabled automatically and a build will be triggered automatically which will build the conda package and upload to [https://anaconda.org/conda-forge](https://anaconda.org/conda-forge)
 * If this is your first contribution, you will be added to the conda-forge [team](https://github.com/orgs/conda-forge/people) and given access to the CI services so that you can stop and restart builds. You will also be given commit rights to the new git repository.
-* If you want to make a change to the recipe, send a [PR](../misc/index.md#term-PR) to the git repository from a fork. Branches of the main repository are used for maintaining different versions only.
+* If you want to make a change to the recipe, send a [PR](../glossary.md#term-PR) to the git repository from a fork. Branches of the main repository are used for maintaining different versions only.
 
 <a id="feedstock-repository-structure"></a>
 
@@ -193,7 +193,7 @@ This file is used to configure how the feedstock is set up and built. Making any
 
 The maintainer's job is to:
 
-- Keep the feedstock updated by merging eventual maintenance [PR](../misc/index.md#term-PR)s from conda-forge's bots.
+- Keep the feedstock updated by merging eventual maintenance [PR](../glossary.md#term-PR)s from conda-forge's bots.
 - Keep the feedstock on par with new releases of the source package by:
   - Bumping the version number and checksum.
   - Making sure that the feedstock's requirements stay accurate.
@@ -449,26 +449,26 @@ Run dependencies are only required during run time of the package. Run dependenc
 
 #### Avoid external dependencies
 
-As a general rule: all dependencies have to be packaged by conda-forge as well. This is necessary to assure [ABI](../misc/index.md#term-ABI) compatibility for all our packages.
+As a general rule: all dependencies have to be packaged by conda-forge as well. This is necessary to assure [ABI](../glossary.md#term-ABI) compatibility for all our packages.
 
 There are only a few exceptions to this rule:
 
-1. Some dependencies have to be satisfied with [CDT](../misc/index.md#term-CDT) packages (see [Core Dependency Tree Packages (CDTs)](knowledge_base.md#cdt-packages)).
+1. Some dependencies have to be satisfied with [CDT](../glossary.md#term-CDT) packages (see [Core Dependency Tree Packages (CDTs)](knowledge_base.md#cdt-packages)).
 2. Some packages require root access (e.g. device drivers) that cannot be distributed by conda-forge. These dependencies should be avoided whenever possible.
 
 <a id="pinning"></a>
 
 #### Pinning
 
-Linking shared c/c++ libraries creates dependence on the [ABI](../misc/index.md#term-ABI) of the library that was used at build time on the package.
+Linking shared c/c++ libraries creates dependence on the [ABI](../glossary.md#term-ABI) of the library that was used at build time on the package.
 The exposed interface changes when previously existing exposed symbols are deleted or modified in a newer version.
 
-It is therefore crucial to ensure that only library versions with a compatible [ABI](../misc/index.md#term-ABI) are used after linking.
+It is therefore crucial to ensure that only library versions with a compatible [ABI](../glossary.md#term-ABI) are used after linking.
 
 In the best case, the shared library you depend on:
 
 - defines a pin in the [list of globally pinned packages](https://github.com/conda-forge/conda-forge-pinning-feedstock/blob/master/recipe/conda_build_config.yaml)
-- exports its [ABI](../misc/index.md#term-ABI) compatible requirements by defining `run_exports` in it's meta.yaml
+- exports its [ABI](../glossary.md#term-ABI) compatible requirements by defining `run_exports` in it's meta.yaml
 
 In these cases you do not have to worry about version requirements:
 
@@ -480,7 +480,7 @@ requirements:
     - libpng
 ```
 
-In other cases you have to specify [ABI](../misc/index.md#term-ABI) compatible versions manually.
+In other cases you have to specify [ABI](../glossary.md#term-ABI) compatible versions manually.
 
 ```yaml
 requirements:
@@ -552,7 +552,7 @@ But every conda package must have at least *some* tests.
 Sometimes defining tests seems to be hard, e.g. due to:
 
 - tests for the underlying code base may not exist.
-- test suites may take too long to run on limited [CI](../misc/index.md#term-CI) infrastructure.
+- test suites may take too long to run on limited [CI](../glossary.md#term-CI) infrastructure.
 - tests may take too much bandwidth.
 
 In these cases, conda-forge may not be able to execute the prescribed test suite.

diff --git a/docs/maintainer/infrastructure.md b/docs/maintainer/infrastructure.md
@@ -29,7 +29,7 @@ Smithy contains maintenance code for conda-forge, which is used by the `conda-sm
 
 - The rerendering process
 - The recipe linter
-- [CI](../misc/index.md#term-CI) support utils
+- [CI](../glossary.md#term-CI) support utils
 
 `conda-smithy` also contains the command line tool that you should use if you rerender manually from the command line (see [Rerendering feedstocks](updating_pkgs.md#dev-update-rerender)).
 
@@ -54,7 +54,7 @@ Package-wide dependency pins are defined in [conda_build_config.yaml](https://gi
 
 For more information on conda-forge wide package pins, please refer to [Globally pinned packages](pinning_deps.md#globally-pinned-packages).
 
-Please open a [PR](../misc/index.md#term-PR) and/or an issue there, if you think a pin needs to be advanced. For more information on updating globally pinned packages, please refer to [Updating package pins](pinning_deps.md#update-pins).
+Please open a [PR](../glossary.md#term-PR) and/or an issue there, if you think a pin needs to be advanced. For more information on updating globally pinned packages, please refer to [Updating package pins](pinning_deps.md#update-pins).
 
 <a id="documentation"></a>
 

diff --git a/docs/maintainer/knowledge_base.md b/docs/maintainer/knowledge_base.md
@@ -1148,7 +1148,7 @@ named `yum_requirements.txt` in the `recipe` directory of a feedstock.
 
 There are only very few situations where dependencies installed by yum are acceptable. These cases include
 
-- satisfying the requirements of [CDT](../misc/index.md#term-CDT) packages during test phase
+- satisfying the requirements of [CDT](../glossary.md#term-CDT) packages during test phase
 - installing packages that are only required for testing
 
 After changing `yum_requirements.txt`, [rerender](updating_pkgs.md#dev-update-rerender) to update the configuration.

diff --git a/docs/maintainer/pinning_deps.md b/docs/maintainer/pinning_deps.md
@@ -84,7 +84,7 @@ There is additional documentation on this pinning scheme in [the conda docs](htt
 
 ## Specifying run_exports
 
-The `run_exports` feature can be used to specify the versions that are [ABI](../misc/index.md#term-ABI) compatible with the built version. This leads to higher flexibility of choosable packages, without breakages due to incompatibilities.
+The `run_exports` feature can be used to specify the versions that are [ABI](../glossary.md#term-ABI) compatible with the built version. This leads to higher flexibility of choosable packages, without breakages due to incompatibilities.
 
 Packages that depend on a package with `run_exports` can choose to overwrite this behavior using the `build/ignore_run_exports` key.
 
@@ -123,7 +123,7 @@ be added by hand. To do this, follow these steps:
 1. Create a new migration yaml by copying [example.exyaml](https://github.com/conda-forge/conda-forge-pinning-feedstock/blob/master/recipe/migrations/example.exyaml) in the `conda-forge/conda-forge-pinning` repository.
 2. Change the migration yaml to reflect the package and version to be migrated
 3. Write a migrator for propagating the pin changes.
-4. Propose the changes as a [PR](../misc/index.md#term-PR) to [conda-forge/conda-forge-pinning-feedstock](https://github.com/conda-forge/conda-forge-pinning-feedstock).
+4. Propose the changes as a [PR](../glossary.md#term-PR) to [conda-forge/conda-forge-pinning-feedstock](https://github.com/conda-forge/conda-forge-pinning-feedstock).
 5. Once accepted the migration will begin. The migration status can be monitored at [https://conda-forge.org/status](https://conda-forge.org/status).
 6. After the migration is complete, a new PR can be issued to [conda-forge/conda-forge-pinning-feedstock](https://github.com/conda-forge/conda-forge-pinning-feedstock) to:
    - Remove the migrator yaml for the completed migration

diff --git a/docs/maintainer/updating_pkgs.md b/docs/maintainer/updating_pkgs.md
@@ -31,12 +31,12 @@ All maintainers are given push access to the feedstocks that they maintain.
 This means that a maintainer can create branches in the main repo.
 For updates, using a branch in the main repo is discouraged because,
 
-1. [CI](../misc/index.md#term-CI) is run on both the branch and the PR.
+1. [CI](../glossary.md#term-CI) is run on both the branch and the PR.
 
-   This wastes [CI](../misc/index.md#term-CI) resources
+   This wastes [CI](../glossary.md#term-CI) resources
 2. Branches are automatically published.
 
-   This means if you push a version update to a branch and then create a [PR](../misc/index.md#term-PR), conda packages will be published to anaconda.org before the PR is merged.
+   This means if you push a version update to a branch and then create a [PR](../glossary.md#term-PR), conda packages will be published to anaconda.org before the PR is merged.
 
 :::warning[Important]
 
@@ -131,7 +131,7 @@ Please follow the following guidelines while updating recipes:
 
 ## Rerendering feedstocks
 
-Rerendering is conda-forge's way to update the files common to all feedstocks (e.g. README, [CI](../misc/index.md#term-CI) configuration, pinned dependencies).
+Rerendering is conda-forge's way to update the files common to all feedstocks (e.g. README, [CI](../glossary.md#term-CI) configuration, pinned dependencies).
 
 Rerendering can be done in two ways:
 
@@ -184,7 +184,7 @@ This process takes time, though, and pull requests will not be opened to all fee
 
 ## Testing changes locally
 
-If you have docker installed on your system, you can test builds locally on your machine under the same settings as it is built by our [CI](../misc/index.md#term-CI).
+If you have docker installed on your system, you can test builds locally on your machine under the same settings as it is built by our [CI](../glossary.md#term-CI).
 
 If you want to build and test updates to a feedstock locally, go to the root
 feedstock directory and run: