Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: clarify relationship between owner and owner_account (again) #2125

Merged
merged 3 commits into from
Jun 30, 2021
Merged

docs: clarify relationship between owner and owner_account (again) #2125

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
17ff754
docs: clarify relationship between `owner` and `owner_account` (again)
dgw Jun 28, 2021
974f3ac
docs: fix typo in `plugin/anatomy.rst`
dgw Jun 28, 2021
da5267d
docs: rework misleading inline comment style in config examples
dgw Jun 28, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 14 additions & 16 deletions docs/source/configuration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,17 +131,10 @@ on the IRC server the bot connects to.
Owner & Admins
--------------

A Sopel instance must have exactly one owner. This is configured either by
:attr:`~CoreSection.owner_account` if the IRC server supports IRCv3 accounts,
or by :attr:`~CoreSection.owner`. If ``owner_account`` is set, ``owner`` will
be ignored.

.. important::

Even if ``owner_account`` is set, ``owner`` **must** still have a value.

This is silly, we know. The plan for Sopel 8 is to require only one value
or the other.
A Sopel instance must have exactly one owner. This is configured by the
:attr:`~CoreSection.owner` setting. If the IRC server supports IRCv3 accounts,
Sopel can use :attr:`~CoreSection.owner_account` to increase the security of
ownership verification.

The same instance can have multiple admins. Similarly, it can be configured
by :attr:`~CoreSection.admin_accounts` or by :attr:`~CoreSection.admins`. If
Expand All @@ -151,25 +144,30 @@ Example owner & admin configurations::

# Using nickname matching
[core]
owner = dgw
owner = dgw # used for alerts and ownership verification
dgw marked this conversation as resolved.
Show resolved Hide resolved
admins =
Exirel
HumorBaby

# Using account matching
[core]
owner_account = dgw
owner = dgw # used for alerts only
owner_account = dgws_account # used for ownership verification
admin_accounts =
Exirel
HumorBaby
# ignored when owner_account is set,
# but MUST NOT be empty
owner = dgw

Both ``owner_account`` and ``admin_accounts`` are safer to use than
nick-based matching, but the IRC server must support accounts.
(Most, sadly, do not as of late 2019.)

.. important::

The :attr:`~CoreSection.owner` setting should **always** contain the bot
owner's nickname, even when using :attr:`~CoreSection.owner_account`. Both
Sopel and plugins may send important messages or notices to the owner
using ``bot.config.core.owner`` as the recipient.


IRC Server
==========
Expand Down
2 changes: 1 addition & 1 deletion docs/source/plugin/anatomy.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,7 +136,7 @@ manipulation. There are two cases to consider:
* A :term:`Named rule` is already named (by definition), so it uses its name
directly as rule label. This can't be overridden by a decorator.

This label is particulary useful for bot owners who want to disable a rule in
This label is particularly useful for bot owners who want to disable a rule in
a specific channel. In the following example, the ``say_hello`` rule from the
``hello`` plugin is disabled in the ``#rude`` channel:

Expand Down