Skip to content

Add section about metadata #944

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

Merged
gilgongo merged 1 commit into from
Aug 5, 2023
Merged

Add section about metadata #944

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
35 changes: 35 additions & 0 deletions _posts/2023-07-30-Server-Metadata.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
---
layout: post
title: "Allow or block bots"
lang: "en"
heading: "Metadata for servers"
---

To provide information about Servers and specify policies for bots, a server owner can add metadata to their server welcome message. This page describes metadata a welcome message might include.

<!--more-->

You can add metadata to your server for many purposes. Adding contact information like the E-Mail or Website of the Server administrator helps users to contact the administrator if something goes wrong with the server. Also adding policies for bots allows them to judge if they can or cannot connect to the server.
Copy link
Copy Markdown
Contributor

@mcfnord mcfnord Jul 30, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It only helps if there's a straightforward way for users to find or use this information. Including this information in clear text is arguably much more useful than hiding it as our HTML will do. If I wanted users to easily contact me, providing a visible email or website address seems foolproof, while a hidden metadata entry is... useless at this point, right? So I'm not sure we've thought through how this guidance would help. Eventually it might be discoverable at both Jamulus Explorer and Live, but until then, I'm not sure it's worth recommending.

Copy link
Copy Markdown
Member Author

@ann0see ann0see Jul 30, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tools can extract it - and probably also jamulus explorer could parse it and display it in a new field.

Copy link
Copy Markdown
Contributor

@mcfnord mcfnord Jul 30, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The user's discovery is highly diminished vs. clear text. I don't see how we could beat guidance that says, "Hey, put your email address in your welcome message." Putting it in hidden text gains us... what?

Copy link
Copy Markdown
Contributor

@pljones pljones Jul 31, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The point of "metadata" is not to be human-readable. It's directed at machines and should be in an easily machine-parseable format.

Anyone can put any human-visible text in their welcome message already.

Using <!-- and --> allows a parser to delimit the metadata - which, for a parser, is fairly necessary - otherwise it's guesswork.

The idea here was that we'd say, "Hey, if you want to tag up your server so it has machine readable data, here's how we suggest you do it."

Then if someone says "Hey, it'd be cool if you tag your server up with <some info I want to parse> using <this suggested tag>" we already have that idea embedded in the documentation and it's not alien to server operators. It would be down to the person wanting to scrape the information to make sure they weren't clashing with anything that existed for other purposes. It might be that we end up with a page logging metadata tags and their meanings, as people add them - but that wouldn't be owned by anyone other than the people using the tags.

It's definitely never going to be something Jamulus itself is interested in.

Copy link
Copy Markdown
Contributor

@mcfnord mcfnord Jul 31, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not? Require an admin contact email someday. You could announce new releases via email. It'd be grand.

Copy link
Copy Markdown
Member Author

@ann0see ann0see Jul 31, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this goes against the policy of Jamulus being open. Also alerting people via E-Mail should be opt in.

The point of "metadata" is not to be human-readable. It's directed at machines and should be in an easily machine-parseable format.

Exactly. I think we should drop the talk about admin contact here.
Focus on a generalized metadata format.

Copy link
Copy Markdown
Contributor

@mcfnord mcfnord Jul 31, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've suggested focusing on bot policy, and also suggested brainstorming good candidates for metadata usage. Surely someone could think of more than one usage of this generalized format before you tout it.


## How to add metadata

Metadata should be added to the welcome message. If you are running a GUI server, paste the metadata into the welcome message box. Headless servers can use the `--welcomemessage` CLI argument to provide a path to a file containing the welcome message.

## Format of metadata

A metadata tag is a HTML comment that looks like this:

```html
<!-- META: <tagname> <value> -->
```

For example, to add a way to contact the server administrator, a tag could look like this:

```html
<!-- META: admincontact admin@example.com -->
```

You can modify and paste this into your welcome message.

See [this discussion](https://github.com/orgs/jamulussoftware/discussions/3086) for more information.

6 changes: 6 additions & 0 deletions wiki/en/Running-a-Server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -286,6 +286,12 @@ You can see the result of these commands if you run `systemctl status jamulus`,

---

## Adding metadata to the Server

You can add metadata to the welcome message of a Server to add additional, hidden information like contact information or policy requests for bots (this is comparable to [robots.txt](https://en.wikipedia.org/wiki/Robots.txt)). See the [Community Knowledge Base entry about metadata](/kb/2023/07/30/Server-Metadata.html) for more information.

---

## Servers on the desktop

Jamulus can run in Server mode in the graphical environment of a computer. This gives you a graphical user interface to control most of the settings. To do this, first [install Jamulus for your platform](Getting-Started), then do one of the following:
Expand Down