Merge pull request #9978 from circleci/DOCSS-1799-content-updates

Orbs content updates

Author: rosieyohannan

…es/author/pages/orb-development-kit.adoc archive/orbs/orb-development-kit.adocdocs/orbs/modules/author/pages/orb-development-kit.adoc renamed to archive/orbs/orb-development-kit.adoc docs/orbs/modules/author/pages/orb-development-kit.adoc renamed to archive/orbs/orb-development-kit.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

…/modules/author/pages/creating-orbs.adoc …rbs/publishing-orbs-to-the-registry.adocdocs/orbs/modules/author/pages/creating-orbs.adoc renamed to archive/orbs/publishing-orbs-to-the-registry.adoc docs/orbs/modules/author/pages/creating-orbs.adoc renamed to archive/orbs/publishing-orbs-to-the-registry.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 what you need it for and how you want to share it.
+
+* **Registry orbs**: Best for public sharing or when you need semantic versioning.
+* **URL orbs**: Best for sharing across your organization but not externally. Requires hosting and administrative allow-list management.
+* **Inline orbs**: Best for project-specific reusable configuration and testing before extracting config into a URL or registry orb. No publishing required, defined directly in your config file.
+
+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 that I have 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-author-faq-snip.adoc

@@ -1,30 +1,65 @@
+[#what-types-of-orbs-are-available]
+=== What types of orbs are available?
+
+CircleCI supports three types of orbs:
+
+include::guides:ROOT:partial$orbs/orb-types.adoc[]
+
+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 **registry orbs** when:
+
+* You want to share with the community.
+* You need semantic versioning.
+* You want discoverability in the Orb Registry.
+
+Choose **URL orbs** when:
+
+* You need to share configuration across your organization.
+* You need direct control over updates.
+* Configuration contains proprietary logic.
+
+Choose **inline orbs** when:
+
+* Configuration is specific to one project.
+* You want zero publishing overhead.
+* You are learning about orbs and want to experiment.
+* You want to test out packaging some configuration before extracting it to a URL or registry orb.
+
+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.

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

@@ -0,0 +1,62 @@
+[.table-scroll]
+--
+[cols=4*, options="header"]
+|===
+| Feature | Registry Orbs | URL Orbs | Inline Orbs
+
+| *Location*
+| Published to Orb Registry, stored in GitHub repository
+| Hosted at accessible URL (GitHub, S3, etc.)
+| Defined in config file
+
+| *Sharing scope*
+| Public or private across organizations
+| Organization-wide (with allow-list)
+| Project-specific only
+
+| *Versioning*
+| Semantic versioning
+| Manual (Git branches, tags, commits)
+| None
+
+| *VCS support*
+| Registry orbs are hosted in GitHub only but can be used by all CircleCI users if public
+| GitHub, Bitbucket
+| GitHub, GitLab, Bitbucket
+
+| *Mutability*
+| Immutable
+| Mutable
+| Mutable (edit config directly)
+
+| *Updates*
+| Publish new semantic version (immutable)
+| Update hosted file (5-minute cache)
+| Edit config file directly
+
+| *Access control*
+| Namespace permissions
+| Organization allow-list
+| Repository access only
+
+| *Best for*
+| Community sharing, public packages, certified orbs
+| Organization-wide shared config, overriding config, proprietary logic
+| Project-specific reusable config, learning, testing
+
+| *Choose this type when:*
+a| * You want to share your orb with the community.
+* You want to use semantic versioning for your orb.
+* You want your orb to be discoverable in the CircleCI Orb Registry.
+* You want to leverage the orb development kit and automated CI/CD pipeline.
+a| * You want to use centralized configuration for your organization.
+* You need to share configuration within your organization.
+* You need direct control over updates and distribution.
+* You need to use proprietary or confidential configurations.
+a| * Configuration is specific to a single project.
+* You want zero publishing or hosting overhead.
+* You're learning about orbs and want to experiment.
+* You need immediate changes without any publishing delay.
+
+|===
+--