Skip to content

Commit

Permalink
docs: Harmonise references to Cilium Slack
Browse files Browse the repository at this point in the history 
We link to Cilium Slack at multiple locations in Cilium's documentation.
The way we do it is far from consistent:

- We usually provide a direct link to the Slack instance
- ... Which, over time, resulted in at least 13 occurrences of the same
  URL https://cilium.herokuapp.com
- Sometimes, we create an indirect link to a "_slack" target, pointing
  to the gettinghelp.rst page
- Some other times, we use other indirect links pointing to the
  glossary.
- At some locations, we also mention that users can get invites to the
  Slack instance. As far as I know, these invites are no longer
  necessary.

Let's try to clean this up.

- Create a target link in the RST epilogue in conf.py, so we can
  reference it from any location.
- Call this link everywhere we need, using `Cilium Slack`_ in a
  consistent fashion.
- Format most channel names as inline literals.
- Improve formatting (not the content) of some paragraphs that already
  get updates for Slack references: rewrap, remove trailing spaces, etc.

Signed-off-by: Quentin Monnet <quentin@isovalent.com>
  • Loading branch information
@qmonnet
qmonnet committed Aug 9, 2023
1 parent 2a5f632 commit b2c5deb
Show file tree
Hide file tree
Showing 31 changed files with 161 additions and 147 deletions.
3 changes: 2 additions & 1 deletion Documentation/bpf/toolchain.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,8 @@ In order to run through all BPF selftests, the following command is needed:
$ sudo make run_tests
If you see any failures, please contact us on Slack with the full test output.
If you see any failures, please contact us on `Cilium Slack`_ with the full
test output.

Compiling iproute2
``````````````````
Expand Down
3 changes: 3 additions & 0 deletions Documentation/check-build.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -100,10 +100,13 @@ run_linter() {

CONF_PY_ROLES=$(sed -n "/^extlinks = {$/,/^}$/ s/^ *'\([^']\+\)':.*/\1/p" conf.py | tr '\n' ',')
CONF_PY_SUBSTITUTIONS="$(sed -n 's/^\.\. |\([^|]\+\)|.*/\1/p' conf.py | tr '\n' ',')release"
CONF_PY_TARGET_NAMES="(cilium slack)"
ignored_messages="("
ignored_messages="${ignored_messages}bpf/.*\.rst:.*: \(INFO/1\) Enumerated list start value not ordinal"
ignored_messages="${ignored_messages}|Hyperlink target .*is not referenced\."
ignored_messages="${ignored_messages}|Duplicate implicit target name:"
ignored_messages="${ignored_messages}|\(ERROR/3\) Indirect hyperlink target \".*\" refers to target \"${CONF_PY_TARGET_NAMES}\", which does not exist."
ignored_messages="${ignored_messages}|\(ERROR/3\) Unknown target name: \"${CONF_PY_TARGET_NAMES}\"."
ignored_messages="${ignored_messages})"
# Filter out the AttributeError reports that are due to a bug in rstcheck,
# see https://github.com/rstcheck/rstcheck-core/issues/3.
Expand Down
104 changes: 52 additions & 52 deletions Documentation/community/community.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,70 +20,70 @@ Zoom call open to everyone. During that time, we discuss:
If you want to discuss something during the next meeting's open session,
you can add it to `the meeting's Google doc
<https://docs.google.com/document/d/1Y_4chDk4rznD6UgXPlPvn3Dc7l-ZutGajUv1eF0VDwQ/edit#>`_.
The Zoom link to the meeting is available in the #development Slack
The Zoom link to the meeting is available in the ``#development`` Slack
channel and in `the meeting notes
<https://docs.google.com/document/d/1Y_4chDk4rznD6UgXPlPvn3Dc7l-ZutGajUv1eF0VDwQ/edit#>`_.

Slack
=====

Our Cilium & eBPF Slack is the main discussion space for the Cilium community.
Click `here <https://cilium.herokuapp.com>`_ to request an invite.
Our `Cilium & eBPF Slack <Cilium Slack_>`_ is the main discussion space for the
Cilium community.

Slack channels
--------------

==================== ==========================================================
Name Purpose
==================== ==========================================================
#general General user discussions & questions
#hubble Questions on Hubble
#kubernetes Kubernetes-specific questions
#networkpolicy Questions on network policies
#release Release announcements only
#service-mesh Questions on Cilium Service Mesh
#tetragon Questions on Tetragon
==================== ==========================================================
======================== ======================================================
Name Purpose
======================== ======================================================
``#general`` General user discussions & questions
``#hubble`` Questions on Hubble
``#kubernetes`` Kubernetes-specific questions
``#networkpolicy`` Questions on network policies
``#release`` Release announcements only
``#service-mesh`` Questions on Cilium Service Mesh
``#tetragon`` Questions on Tetragon
======================== ======================================================

You can join the following channels if you are looking to contribute to
Cilium code, documentation, or website:

==================== ==========================================================
Name Purpose
==================== ==========================================================
#development Development discussions around Cilium
#ebpf-go-dev Development discussion for the `eBPF Go library`_
#git GitHub notifications
#sig-* SIG-specific discussions (see below)
#testing Testing and CI discussions
#cilium-website Development discussions around cilium.io
==================== ==========================================================
======================== ======================================================
Name Purpose
======================== ======================================================
``#development`` Development discussions around Cilium
``#ebpf-go-dev`` Development discussion for the `eBPF Go library`_
``#git`` GitHub notifications
``#sig-``\* SIG-specific discussions (see below)
``#testing`` Testing and CI discussions
``#cilium-website`` Development discussions around cilium.io
======================== ======================================================

If you are interested in eBPF, then the following channels are for you:

==================== ==========================================================
Name Purpose
==================== ==========================================================
#ebpf General eBPF questions
#ebpf-go Questions on the `eBPF Go library`_
#ebpf-lsm Questions on BPF Linux Security Modules (LSM)
#echo-news Contributions to `eCHO News`_
#ebpf-for-windows Discussions around eBPF for Windows
==================== ==========================================================
======================== ======================================================
Name Purpose
======================== ======================================================
``#ebpf`` General eBPF questions
``#ebpf-go`` Questions on the `eBPF Go library`_
``#ebpf-lsm`` Questions on BPF Linux Security Modules (LSM)
``#echo-news`` Contributions to `eCHO News`_
``#ebpf-for-windows`` Discussions around eBPF for Windows
======================== ======================================================

.. _eBPF Go library: https://github.com/cilium/ebpf
.. _eCHO News: https://cilium.io/newsletter/

Our Slack hosts channels for eBPF and Cilium-related events online and in
person.

==================== ==========================================================
Name Purpose
==================== ==========================================================
#ciliumcon CiliumCon
#ctf Cilium and eBPF capture-the-flag challenges
#ebpf-summit eBPF Summit
==================== ==========================================================
======================== ======================================================
Name Purpose
======================== ======================================================
``#ciliumcon`` CiliumCon
``#ctf`` Cilium and eBPF capture-the-flag challenges
``#ebpf-summit`` eBPF Summit
======================== ======================================================

How to create a Slack channel
-----------------------------
Expand All @@ -94,7 +94,7 @@ How to create a Slack channel
4. Find two Cilium committers to comment in the issue that they approve the
creation of the Slack channel
5. Not all Slack channels need to be listed on this page, but you can submit a
PR if you would like to include it here.
PR if you would like to include it here.

Special Interest Groups
=======================
Expand All @@ -106,16 +106,16 @@ The following is a list of special interest groups (SIG) that are meeting on a
regular interval. See the respective slack channel for exact meeting cadence
and meeting links.

====================== ===================================== ============= ================================================================================
SIG Meeting Slack Description
====================== ===================================== ============= ================================================================================
Datapath On demand #sig-datapath Development discussions for Linux and eBPF code used in Cilium.
Documentation None #sig-docs Documentation, Helm references, and translations.
Envoy On demand #sig-envoy Envoy, Istio and maintenance of all L7 protocol parsers.
Hubble During community meeting #sig-hubble All Hubble-related code: Server, UI, CLI and Relay.
Policy None #sig-policy Network policy and enforcement.
Release Management None #launchpad Release management and backport coordination.
====================== ===================================== ============= ================================================================================
====================== ===================================== ================= ============================================================================
SIG Meeting Slack Description
====================== ===================================== ================= ============================================================================
Datapath On demand ``#sig-datapath`` Development discussions for Linux and eBPF code used in Cilium.
Documentation None ``#sig-docs`` Documentation, Helm references, and translations.
Envoy On demand ``#sig-envoy`` Envoy, Istio and maintenance of all L7 protocol parsers.
Hubble During community meeting ``#sig-hubble`` All Hubble-related code: Server, UI, CLI and Relay.
Policy None ``#sig-policy`` Network policy and enforcement.
Release Management None ``#launchpad`` Release management and backport coordination.
====================== ===================================== ================= ============================================================================

How to create a SIG
-------------------
Expand All @@ -124,6 +124,6 @@ How to create a SIG
2. Specify the title "SIG-Request: <Name>"
3. Provide a description
4. Find two Cilium committers to support the SIG.
5. Ask on #development to get the Slack channel and Zoom meeting created
5. Ask on ``#development`` to get the Slack channel and Zoom meeting created
6. Submit a PR to update the documentation to get your new SIG listed

20 changes: 11 additions & 9 deletions Documentation/community/governance/commit_access.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -130,11 +130,13 @@ The Maintainers may also choose to delegate working with the CNCF to non-Maintai
Code of Conduct
~~~~~~~~~~~~~~~

`Code of Conduct <https://github.com/cilium/cilium/blob/main/CODE_OF_CONDUCT.md>`__
violations by community members will be discussed and resolved on the private
committers Slack channel. If the reported Code of Conduct violator is a Maintainer, the
Maintainers will instead designate two Maintainers to work with the
`CNCF CoC Committee <https://www.cncf.io/conduct/procedures/>`__.
`Code of Conduct`_ violations by community members will be discussed and
resolved on the private committers channel on `Cilium Slack`_. If the reported
Code of Conduct violator is a Maintainer, the Maintainers will instead
designate two Maintainers to work with the `CNCF CoC Committee`_.

.. _Code of Conduct: https://github.com/cilium/cilium/blob/main/CODE_OF_CONDUCT.md
.. _CNCF CoC Committee: https://www.cncf.io/conduct/procedures/

Granting Commit Access
----------------------
Expand Down Expand Up @@ -165,7 +167,7 @@ demonstrated the following in their interaction with the project:
The process to grant commit access to a candidate is simple:

- An existing committer nominates the candidate by sending a message in the
#committers Slack channel to all existing committers with information
``#committers`` Slack channel to all existing committers with information
substantiating the contributions of the candidate in the areas described
above.

Expand Down Expand Up @@ -203,7 +205,7 @@ The process to grant commit access to a candidate is simple:
discussion, those remarks may optionally be summarized and re-posted
to the channel. The final vote summary does not need to be deleted.

#. Invite the new committer to the #committers Slack channel.
#. Invite the new committer to the ``#committers`` Slack channel.

#. Add the new committer to the list in MAINTAINERS.md_.

Expand Down Expand Up @@ -349,8 +351,8 @@ decide an issue. If the maintainers themselves cannot decide an issue, the
issue will be resolved by voting. The voting process is a simple majority in
which each committer and each maintainer receives one vote.

Votes are done in the Slack channel #committers using Slack polls. A failure to
vote is an implicit abstention.
Votes are done in the Slack channel ``#committers`` using Slack polls. A
failure to vote is an implicit abstention.

.. _vote_limit:

Expand Down
26 changes: 14 additions & 12 deletions Documentation/community/roadmap.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -171,15 +171,18 @@ production.
Codebase modularization
~~~~~~~~~~~~~~~~~~~~~~~

As the project is growing in complexity it is becoming increasingly important to be able
to divide it into more manageable chunks. To achieve this, we're working on modularizing the
codebase and going from a tightly coupled design (one large initialization and configuration)
to a more loosely coupled design of mostly self-contained modules. This will make Cilium
internals easier to comprehend, test and extend.

Contributions in this area are very welcome. To get started, take a look at the :ref:`guide-to-the-hive`
documentation and the issues referenced from `modularization meta issue <modularization-issue_>`_.
If you have any questions or ideas please join us on the #sig-modularization channel on `Cilium Slack <slack_>`_.
As the project is growing in complexity it is becoming increasingly important
to be able to divide it into more manageable chunks. To achieve this, we're
working on modularizing the codebase and going from a tightly coupled design
(one large initialization and configuration) to a more loosely coupled design
of mostly self-contained modules. This will make Cilium internals easier to
comprehend, test and extend.

Contributions in this area are very welcome. To get started, take a look at the
:ref:`guide-to-the-hive` documentation and the issues referenced from
`modularization meta issue <modularization-issue_>`_. If you have any questions
or ideas please join us on the ``#sig-modularization`` channel on `Cilium
Slack`_.

.. _rm-influence:

Expand All @@ -199,8 +202,8 @@ details of our pull request process and expectations, along with instructions
for setting up your development environment.

We encourage you to discuss your ideas for significant enhancements and feature
requests on the #development channel on `Cilium Slack <slack_>`_, bring them to
the :ref:`weekly-community-meeting`, and/or create a `CFP design doc`_.
requests on the ``#development`` channel on `Cilium Slack`_, bring them to the
:ref:`weekly-community-meeting`, and/or create a `CFP design doc`_.

This roadmap does not give date commitments since the work is dependent on the
community. If you're looking for commitments to apply engineering resources to
Expand All @@ -226,7 +229,6 @@ anything other than trivial fixes.
.. _Hubble OpenTelemetry collector: https://github.com/cilium/hubble-otel
.. _CI improvements: https://github.com/cilium/cilium/issues?q=is%3Aopen+is%3Aissue+label%3Aarea%2FCI-improvement
.. _good-first-issue: https://github.com/cilium/cilium/labels/good-first-issue
.. _slack: https://cilium.io/slack
.. _enterprise: https://cilium.io/enterprise
.. _CFP design doc: https://github.com/cilium/design-cfps/tree/main
.. _modularization-issue: https://github.com/cilium/cilium/issues/23425
5 changes: 5 additions & 0 deletions Documentation/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,11 @@
.. |IMAGE_TAG| replace:: \\{i}
""".format(s=scm_web, b=branch, a=archive_name, f=archive_filename, l=archive_link, c=current_release, n=next_release, h=chart_release, g=go_release, i=image_tag, v=chart_version)

# Make Slack link globally available.
rst_epilog += """
.. _Cilium Slack: https://cilium.herokuapp.com
"""

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
Expand Down
24 changes: 15 additions & 9 deletions Documentation/configuration/argocd-issues.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -83,13 +83,19 @@ Solution
This `pull request <https://github.com/argoproj/argo-cd/pull/8371>`__ fixed this issue in Argo CD's `v2.3.0 release <https://github.com/argoproj/argo-cd/releases/tag/v2.3.0>`__.
Upgrade your Argo CD and check if ``helm template`` with ``serviceMonitor`` enabled still fails.


.. note::
Note that when using ``helm template``, it is highly recommended you set ``--kube-version`` and ``--api-versions`` with the values matching your target Kubernetes cluster.
Helm charts such as Cilium's often conditionally enable certain Kubernetes features based on their availability (beta vs stable) on the target cluster.

By specifying ``--api-versions=monitoring.coreos.com/v1`` you should be able to pass validation with ``helm template``.


If you have an issue with Argo CD that's not outlined above, check this `list of Argo CD related issues on GitHub <https://github.com/cilium/cilium/issues?q=is%3Aissue+argocd>`__.
If you can't find an issue that relates to yours, create one and/or seek help on the :term:`Slack channel`.

When using ``helm template``, it is highly recommended you set
``--kube-version`` and ``--api-versions`` with the values matching your
target Kubernetes cluster. Helm charts such as Cilium's often conditionally
enable certain Kubernetes features based on their availability (beta vs
stable) on the target cluster.

By specifying ``--api-versions=monitoring.coreos.com/v1`` you should be
able to pass validation with ``helm template``.

If you have an issue with Argo CD that's not outlined above, check this `list
of Argo CD related issues on GitHub
<https://github.com/cilium/cilium/issues?q=is%3Aissue+argocd>`__.
If you can't find an issue that relates to yours, create one and/or seek help
on `Cilium Slack`_.
2 changes: 1 addition & 1 deletion Documentation/contributing/development/contributing_guide.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -282,7 +282,7 @@ Getting a pull request merged

#. Once the PR has been reviewed and the CI tests have passed, the PR will be
merged by one of the repository owners. In case this does not happen, ping
us on Slack in the #development channel.
us on `Cilium Slack`_ in the ``#development`` channel.

.. _organization member: https://github.com/cilium/community/blob/main/CONTRIBUTOR-LADDER.md#organization-member

Expand Down
6 changes: 3 additions & 3 deletions Documentation/contributing/development/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,6 @@ understand the workflow of getting these changes reviewed and merged upstream.
hubble
introducing_new_crds

The best way to get help if you get stuck is to ask a question on the `Cilium
Slack channel <https://cilium.herokuapp.com>`_. With Cilium contributors
across the globe, there is almost always someone available to help.
The best way to get help if you get stuck is to ask a question on `Cilium
Slack`_. With Cilium contributors across the globe, there is almost always
someone available to help.

0 comments on commit b2c5deb

Please sign in to comment.