Restructure content to better present three orb options, URL, inline and registry

docs/orbs/modules/author/pages/creating-orbs.adoc → archive/publishing-orbs-to-the-registry.adoc

@@ -1,20 +1,22 @@
-= Publishing orbs
+= Publishing orbs to the orb registry
 :page-platform: Cloud
 :page-description: Publishing Orbs to the Orb Registry
 :experimental:
+:page-aliases: creating-orbs
 
-This guide covers the steps required to publish an orb.
+This guide covers the steps required to publish a registry orb to the link:https://circleci.com/developer/orbs[orb registry].
 
 [#introduction]
 == Introduction
 
-After authoring your orb, you can publish it with a xref:orb-concepts.adoc#semantic-versioning[semantically versioned] tag, and the orb will appear on the link:https://circleci.com/developer/orbs[Orb Registry].
+After authoring your orb, you can publish it with a xref:use:orb-concepts.adoc#semantic-versioning[semantically versioned] tag, and the orb will appear on the link:https://circleci.com/developer/orbs[orb registry].
 
 CAUTION: If your orb is private, it will not be searchable on the Orb Registry. However, the URL will be accessible to authenticated users of the orb.
 
+.Flow diagram of the orb registry publishing process.
 image::guides:ROOT:orb-publishing-process.png[Orb Publishing Process]
 
-If you are publishing your orb using the xref:orb-development-kit.adoc[orb development kit], rather than xref:orb-author-validate-publish.adoc[manually], semantic releases are straight-forward using the steps set out in this section. You can find a simplified version of the publishing process in the link:https://github.com/CircleCI-Public/Orb-Template/blob/main/README.md[README.md] file that the `circleci orb init` command generates at the start of the authoring process.
+If you are publishing your orb using the xref:orb-author.adoc#orb-development-kit[orb development kit], rather than xref:manual-orb-authoring-process.adoc[manually], semantic releases are straight-forward using the steps set out in this section. You can find a simplified version of the publishing process in the link:https://github.com/CircleCI-Public/Orb-Template/blob/main/README.md[README.md] file that the `circleci orb init` command generates at the start of the authoring process.
 
 [#issue-a-new-release-with-the-orb-development-kit]
 == Issue a new release with the orb development kit

docs/guides/modules/ROOT/partials/faq/orb-author-faq-snip.adoc

@@ -1,49 +1,60 @@
+[#which-orb-type-should-i-author]
+=== Which orb type should I author?
+
+The type of orb you should author depends on your sharing needs:
+
+* **Inline orbs**: Best for project-specific reusable configuration. No publishing required, defined directly in your config file.
+* **URL orbs**: Best for sharing across your organization. Requires hosting and organization allow-list management.
+* **Registry orbs**: Best for public sharing or when you need semantic versioning. Requires CircleCI CLI and publishing process.
+
+See xref:orbs:use:orb-intro.adoc#choosing-an-orb-type[Choosing an Orb Type] for detailed guidance.
+
 [#possible-to-delete-orb]
-=== Is it possible to delete an orb I've created?
+=== Is it possible to delete a registry orb I've created?
 
-No. Orbs are public by default and immutable, once a version of an orb is published it can not be changed. This is done so users can reasonably expect a known version of an orb will behave the same on every run. Deleting an orb could potentially lead to a failing pipeline in any of its user's projects.
+No. Registry orbs are public by default and immutable, once a version of a registry orb is published it can not be changed. Registry orbs are immutable by design so users can reasonably expect a known version of an orb will behave the same on every run. Deleting an orb could potentially lead to a failing pipeline in any of its user's projects.
 
 Orbs can however be "Unlisted" from the link:https://circleci.com/developer/orbs[Orb registry]. Unlisted orbs still exist and are discoverable via the API or CLI, but will not appear in the Orb Registry results. This may be desired if for instance, an orb is no longer maintained.
 
 ```shell
 circleci orb unlist <namespace>/<orb> <true|false> [flags]
 ```
 
-WARNING: **Use caution when using private orbs.** Currently the `orb source` CircleCI CLI command does not work for _any_ private orbs, regardless if they are listed or unlisted. So unless the Private Orb name is documented before it is unlisted, you will not be able to find the orb through the Orb Registry or the CircleCI CLI. If you believe this happened to you, you can create a link:https://support.circleci.com/hc/en-us[support ticket].
+WARNING: **Use caution when using private orbs.** Currently the `orb source` CircleCI CLI command does not work for _any_ private orbs, regardless if they are listed or unlisted. Unless the private orb name is documented before it is unlisted, you will not be able to find the orb through the orb registry or the CircleCI CLI. If you believe this happened to you, you can create a link:https://support.circleci.com/hc/en-us[Support Ticket].
 
 [#protect-users-api-tokens]
 === How do I protect a user's API tokens and other sensitive information?
 
 Use the `env_var_name` parameter type for the API key parameter. This parameter type will only accept valid POSIX environment variable name strings as input. In the parameter description, it is best practice to mention to the user to add this environment variable.
 
-If you are interested in reading more on this topic, visit the xref:reference:ROOT:reusing-config.adoc#environment-variable-name[Environment variable name] and xref:orbs:author:orbs-best-practices.adoc[Best practices] pages.
+If you are interested in reading more on this topic, visit the xref:reference:ROOT:reusing-config.adoc#environment-variable-name[Environment Variable Name] and xref:orbs:author:orbs-best-practices.adoc[Best Practices] pages.
 
 [#require-user-to-add-an-environment-variable]
 === How can I require a user to add an environment variable?
 
 Create a parameter for the environment variable name, even if it is a statically named environment variable the user _should not_ change. Then, assign it the correct default value. In the parameter description let the user know if this value should not be changed. Either way, consider instructing the user on how they can obtain their API key.
 
-Consider validating required environment variables. See more in the xref:orbs:author:orbs-best-practices.adoc#commands[Orb author best practices] guide.
+Consider validating required environment variables. See more in the xref:orbs:author:orbs-best-practices.adoc#commands[Orb Author Best Practices] guide.
 
-If you are interested in reading more on this topic, visit the xref:reference:ROOT:reusing-config.adoc#environment-variable-name[Environment variable name] and xref:orbs:author:orbs-best-practices.adoc[Best practices] pages.
+If you are interested in reading more on this topic, visit the xref:reference:ROOT:reusing-config.adoc#environment-variable-name[Environment Variable Name] and xref:orbs:author:orbs-best-practices.adoc[Best Practices] pages.
 
 [#what-language-to-write-orb]
 === What language do I use to write an orb?
 
-Orbs are packages of xref:guides:getting-started:introduction-to-yaml-configurations.adoc[CircleCI YAML configuration].
+Orbs are packages of xref:guides:getting-started:introduction-to-yaml-configurations.adoc[CircleCI YAML Configuration].
 
-CircleCI orbs package xref:reference:ROOT:reusing-config.adoc[CircleCI reusable config], such as xref:reference:ROOT:reusing-config.adoc#authoring-reusable-commands[commands], which can execute within a given xref:guides:execution-managed:executor-intro.adoc[executor] defined by either, the user if using a _command_ within a custom job, or by the orb author if using a xref:orbs:author:orb-concepts.adoc#jobs[reusable job]. The environment within which your logic is running may influence your language decisions.
+CircleCI orbs package xref:reference:ROOT:reusing-config.adoc[Reusable Configuration Elements] like xref:reference:ROOT:reusing-config.adoc#authoring-reusable-commands[Commands]. These commands run within an xref:guides:execution-managed:executor-intro.adoc[Executor]—either one the user specifies in a custom job, or one the orb author defines in a xref:orbs:use:orb-concepts.adoc#jobs[Reusable Job]. This execution environment may influence your language decisions.
 
 [#what-programming-languages-command-logic]
 === What programming languages can I write my Command logic in?
 
-POSIX compliant bash is the most portable and universal language. This is the recommended option when you intend to share your orb. Orbs do, however, come with the flexibility and freedom to run other programming languages or tools.
+POSIX compliant Bash is the most portable and universal language. Bash is the recommended option when you intend to share your orb. Orbs do, however, come with the flexibility and freedom to run other programming languages or tools.
 
 ---
 
 **Bash**
 
-Bash is the preferred language as it is most commonly available among all available executors. Bash can (and should) be easily written directly using the native xref:reference:ROOT:configuration-reference.adoc#run[run] command. The default shell on MacOS and Linux will be bash.
+Bash is the preferred language as it is most commonly available among all available executors. Bash should be written directly using the native xref:reference:ROOT:configuration-reference.adoc#run[Run] command. The default shell on macOS and Linux will be Bash.
 
 **Ruby**
 
@@ -94,6 +105,13 @@ steps:
 
 The answer might be both, but it will heavily depend on the task you want to accomplish.
 
-An orb xref:orbs:author:orb-concepts.adoc#commands[command] can be utilized by the user, or even the orb developer, to perform some action within a job. The command itself has no knowledge of the job it is within as the user could utilize it however they wish. A command may be useful, for example, to automatically install a CLI application or go a step further and install and authenticate.
+An orb xref:orbs:use:orb-concepts.adoc#commands[Command] can be utilized by the user, or even the orb developer, to perform some action within a job. The command itself has no knowledge of the job it is within as the user could utilize it however they wish. A command may be useful, for example, to automatically install a CLI application or go a step further and install and authenticate.
+
+A xref:orbs:use:orb-concepts.adoc#jobs[Job] defines a collection of steps and commands within a specific execution environment. A job is highly opinionated as it generally chooses the execution platform to run on and what steps to run. Jobs may offer a useful way to automate tasks such as deployments. A deployment job may look something like this:
+
+* Select a certain execution platform that is known, such as _Python_.
+* Automatically checkout the users code.
+* Install a CLI.
+* Run a deployment command.
 
-A xref:orbs:author:orb-concepts.adoc#jobs[job] defines a collection of steps and commands within a specific execution environment. A job is highly opinionated as it generally chooses the execution platform to run on and what steps to run. Jobs may offer a useful way to automate tasks such as deployments. A deployment job may select a certain execution platform that is known, such as _python_, and automatically checkout the users code, install a CLI, and run a deployment command, all with little to no additional configuration required from the user.
+All without requiring any additional configuration from the user.

docs/guides/modules/ROOT/partials/faq/orb-faq-snip.adoc

@@ -1,30 +1,66 @@
+[#what-types-of-orbs-are-available]
+=== What types of orbs are available?
+
+CircleCI supports three types of orbs:
+
+* **Inline orbs**: Defined directly in your project's `.circleci/config.yml` file. They are project-specific and ideal for reusable configuration within a single project.
+* **URL orbs**: Stored at an accessible URL (like GitHub or S3) and shared across your organization using an allow-list.
+* **Registry orbs**: Published to the CircleCI Orb Registry with semantic versioning, available publicly or privately.
+
+For a detailed comparison, see the xref:orbs:use:orb-concepts.adoc#orb-types-comparison[Orb Types Comparison] section.
+
+[#which-orb-type-should-i-use]
+=== Which orb type should I use?
+
+Choose **inline orbs** when:
+
+* Configuration is specific to one project.
+* You want zero publishing overhead.
+* You're learning about orbs.
+
+Choose **URL orbs** when:
+
+* You need to share configuration across your organization.
+* You need direct control over updates.
+* Configuration contains proprietary logic.
+
+Choose **registry orbs** when:
+
+* You want to share with the community.
+* You need semantic versioning.
+* You want discoverability in the Orb Registry.
+
+See the xref:orbs:use:orb-intro.adoc#choosing-an-orb-type[Choosing an Orb Type] section for more guidance.
+
 [#can-orbs-be-private]
-=== Can orbs be made private?
+=== Can registry orbs be made private?
 
-xref:orbs:use:orb-intro.adoc#public-or-private[Private orbs] are available on any of our link:https://circleci.com/pricing[current plans].
+xref:orbs:use:orb-intro.adoc#public-or-private[Private Registry Orbs] are available on any of our link:https://circleci.com/pricing[Current Plans]. Inline orbs are inherently private to the project. URL orbs are controlled by your organization's allow-list and hosting access.
 
 [#difference-between-commands-and-jobs]
 === What is the difference between commands and jobs?
 
-Both xref:reference:ROOT:reusing-config.adoc#the-commands-key[commands] and xref:reference:ROOT:reusing-config.adoc#authoring-parameterized-jobs[jobs] are elements that can be used within orbs.
+Both xref:reference:ROOT:reusing-config.adoc#the-commands-key[Commands] and xref:reference:ROOT:reusing-config.adoc#authoring-parameterized-jobs[Jobs] are elements that can be used within orbs.
 
-_Commands_ contain one or many xref:reference:ROOT:configuration-reference.adoc#steps[steps], which contain the logic of the orb. Commands generally execute some shell code (bash).
+_Commands_ contain one or many xref:reference:ROOT:configuration-reference.adoc#steps[Steps], which contain the logic of the orb. Commands generally execute some shell code (Bash).
 
-_Jobs_ are a definition of what steps/commands to run and the xref:reference:ROOT:reusing-config.adoc#the-executors-key[executor] to run them in. _Jobs_ invoke commands, and are orchestrated using xref:guides:orchestrate:workflows.adoc#workflows-configuration-examples[workflows].
+_Jobs_ are a definition of what steps/commands to run and the xref:reference:ROOT:reusing-config.adoc#the-executors-key[Executor] to run them in. _Jobs_ invoke commands, and are orchestrated using xref:guides:orchestrate:workflows.adoc#workflows-configuration-examples[Workflows].
 
 [#orbs-on-private-installation-server]
-=== Can orbs be used on a private installation of CircleCI server?
+=== Can orbs be used on a private installation of CircleCI Server?
 
-Orbs can be used with installations of CircleCI server. For information on importing and using orbs for server, see the xref:server-admin:operator:managing-orbs.adoc[CircleCI server managing orbs] page.
+Orbs can be used with installations of CircleCI Server. For information on importing and using orbs for server, see the xref:server-admin:operator:managing-orbs.adoc[CircleCI Server Managing Orbs] page.
 
 [#report-an-issue-with-a-public-orb]
 === How can I report a bug or issue with a public orb?
 
 All public orbs are open source projects. Issues, bug reports, or even pull requests can be made against the orb's git repository. Public orb authors may opt to include a link to the git repo on the orb registry. If the git repo link is unavailable, contact support and we will attempt to contact the author. Alternatively, consider forking the orb and publishing your own version.
 
 [#how-to-use-the-latest-version-of-an-orb]
-=== How do I use the latest version of an orb?
+=== How do I use the latest version of a registry orb?
+
+Registry orbs use semantic versioning. If you set the _major_ version (example: `3`), you will receive all _minor_ and _patch_ updates. If you statically set the version (example: `3.0.0`), no updates will apply. Using a static version is the most deterministic and recommended method.
 
-Orbs use semantic versioning, meaning if you set the _major_ version (example: `3`), you will receive all _minor_ and _patch_ updates, where if you statically set the version (example: `3.0.0`), no updates will apply, this is the most deterministic and recommended method.
+NOTE: Inline orbs do not have versions (updated by editing the config file), and URL orbs use Git-based versioning (branches, tags, or commits) rather than semantic versioning.
 
 WARNING: NOT RECOMMENDED - It is possible to use `@volatile` to receive the last published version of an orb. This is not recommended as breaking changes are expected.