¶ Guidelines
When publishing Presences to our GitHub Repository, we require you to follow a set of guidelines. To some, these strict rules may seem harsh. However, the implementation of these rule sets will keep us and our users from running into issues.
¶ Creation
The general rules of presence development are as follows:
- Presences must be related to the website of choice.
- Presences cannot be made for illegal websites. (for e.g., stressors, drug marketing, child pornography, etc.)
- The file structure must be clean and managed, do not include files which are not specified. (for e.g., vscode and git folders, image and text files, etc.)
- You need to have a proper file structure, drafts are not allowed.
- Presences for websites with (
.onionTLDs) or websites with free domains/hosts (for e.g.,.TK[all free Freenom domains],.RF,GD, etc) are not permitted, exceptions can be made if a proof is presented showing that they paid for the domain. - The domain of the presence must be at least 2 months old.
- Presence that target internal browser pages (like Chrome Web Store,
chrome://,about:pages, etc) are not allowed as they require an experimental flag to be enabled on the user's end and could potentially cause damage to their browsers. - Presences with support for only a single subdomain will not be permitted, as they may seem broken for other pages (like the homepage), exceptions can be made for the policy and contact pages (content that isn't used often) or sites where the other content is unrelated. (for e.g., wikia pages)
- Presences for online radios are only allowed if the radio has at least 100 weekly listeners and 15 concurrent.
- Low quality presences (or ones with little context) are not allowed (for e.g., only showing a logo and text but never changing it again.)
- Including the
distfolder,presence.tsfile,iframe.tsfile, andmetadata.jsonfile is mandatory so the result would be what is represented in the following schema:
presence
├── dist
│ ├── metadata.json
│ └── presence.js
├── presence.ts
└── tsconfig.json
or if you're using a iframe.ts file:
presence
├── dist
│ ├── metadata.json
│ ├── presence.js
│ └── iframe.js
├── presence.ts
├── iframe.ts
└── tsconfig.json
¶ metadata.json
For the convenience of our presence developers, we have provided a schema which you can use to validate the integrity of your
metadatafile. This is entirely optional and is not required during the review process.
It is highly recommended that you organize your
metadatafile in the format shown below, and you must have grammatically correct service names, descriptions, tags, and setting fields. Anything not organized to specifications will not be permitted.
Presences of websites that have explicit content must have the
nsfwtag, and the logo/thumbnail must not contain any of this content.
Each presence has a descriptor file called metadata.json, the metadata has a strict standard and an example of this file can be seem below:
{
"$schema": "https://schemas.premid.app/metadata/1.0",
"author": {
"name": "USER",
"id": "ID"
},
"contributors": [
{
"name": "USER",
"id": "ID"
}
],
"service": "SERVICE",
"altnames": ["SERVICE"],
"description": {
"en": "DESCRIPTION"
},
"url": "URL",
"version": "VERSION",
"logo": "URL",
"thumbnail": "URL",
"color": "#HEX000",
"tags": ["TAG1", "TAG2"],
"category": "CATEGORY",
"regExp": "REGEXP",
"iFrameRegExp": "REGEXP",
"iframe": false,
"settings": [
{
"id": "ID",
"title": "DISPLAY TITLE",
"icon": "FONTAWESOME FREE ICON",
"value": true
},
{
"id": "ID",
"if": {
"ID": true
},
"title": "DISPLAY TITLE",
"icon": "FONTAWESOME FREE ICON",
"value": "\"%song%\" by %artist%",
"placeholder": "use %song% or %artist%"
},
{
"id": "ID",
"title": "DISPLAY TITLE",
"icon": "FONTAWESOME FREE ICON",
"value": 0,
"values": ["1", "2", "etc."]
}
]
}
If a field is listed as optional on the documentation and your presence uses the default value for it, do not include it in the
metadatafile. (for e.g., a presence without iframe support would not need theiframefield.)
All images in the
metadatafile must be hosted oni.imgur.com. Using content hosted on the website is not permitted as they can change the paths and files unwillingly.
A list of fields and their rules are listed below:
¶ $schema
- The schema key must include a dollar sign at the beginning of it, this will signal your text editor that you want to validate your JSON file against a model. As stated earlier, you do not need to include a schema, but if you include it you must take this into account.
¶ author
- The ID value must be your Discord snowflake ID. You can get it by enabling developer mode. Please do not confuse this with your application ID, which is only for your presence.
¶ contributors
- Do not add yourself as a contributor, and do not add someone else as a contributor unless they have helped with the presence.
¶ service
- The service name must be the name of the presence directory. For example, if the presence is located at
/websites/Y/YouTube/, the service name must beYouTube. - You cannot use the url as the service name unless the website uses the url as its official name. If the name is not descriptive and can be considered vague, using the url is required. (for e.g.,
YouTubeis permitted because that is the official name and is descriptive, whileyoutube.comis not.Topis a non-descriptive name, so using the urltop.ggis required.)
¶ altnames
- Only use this in scenerios where a website goes under multiple official names (e.g. Pokémon and 포켓몬스터) or to make it easier to search the presence without using special characters (e.g. Pokémon and Pokemon). Shortened versions of service names go under
tags.
¶ description
- All presences are required to have an English description regardless of the website's prefered language.
- Do not try and translate the description yourself unless you know that language, translators will modify your
metadata.jsonand change the descriptions if necessary.
¶ url
- The url must be a string if the website only uses one domain. If the website uses multiple, make this an array and specify each one.
- Do not include protocols in the url (for e.g.,
httporhttps), and do not include query parameters in the url (for e.g.,www.google.com/search?gws_rd=sslwhich should bewww.google.com)
¶ version
- Always make sure the version number follows semantic versioning standards, which translates to the following scheme:
<NEW-FEATURE>.<HUGE-BUGFIX>.<SMALL-BUGFIX-OR-METADATA-CHANGES>. Anything else like1.0.0.1,1.0,1,1.0.0-BETAor changing1.0.0to2.0.0on a bug fix/small change is not permitted. - The version must always start at
1.0.0unless told otherwise, other versions will not be permitted.
¶ logo
- The logo must be a square image with a
1:1aspect ratio. - The image is required to have a minimum resolution of
512x512pixels. You can upsize the imagine using a tool like waifu2x.
¶ thumbnail
- The thumbnail should preferably be a wide promotional card or a screenshot if the first is not available.
¶ color
- The color must be a hexadecimal value between
#000000and#FFFFFF. - The color string must be prepended with a hash symbol.
¶ tags
- All presences are required to have at least one tag.
- Tags must not include any spaces, slashes, single/double quotation marks, Unicode characters, and should always be lowercase.
- Tags should preferably include alternate service names to make searching easier (for e.g., if an Amazon presence had included AWS support, it would have its tags like
amazon-web-servicesandaws) - You are required to add an
NSFWtag if the presence is for an NSFW website.
¶ category
- The category must be one of the following listed on the documentation.
- The presence must use a category that matches the content of the website. (for e.g., don't use
animewhen the website isn't related to anime).
¶ regExp
iFrameRegExp
- Regular expressions must be valid. Please test your expressions with the tools listed on the documentation.
¶ settings
- If you decide to make a format string (for e.g.,
%song% by %artist%), you must have the variables surrounded by a percent sign on either side. Variables like%var,var%, or%%var%%and anything in between are not permitted for the sake of standardization. - The name of settings must not be in all capital letters. For example, names such as
SHOW BROWSING STATUSwill not be permitted; however, names such asShow Browsing StatusorShow browsing statusare permitted. - Adding custom strings to the Localization Repository to later be used within the
multiLanguagesetting is only allowed if the presence has already been released before and has aquired at least 1000 users.
¶ presence.ts
The code you write must be well-written and must be readable and all strings must be grammatically correct (grammar errors on websites can be ignored).
Each presence follows a strict linting ruleset which will be checked during the review process. A couple of recommendations can be seen below.
Here is a list of rules you must follow when writing your presence.ts file:
- Always declare a new instance of the
Presenceclass before any other variable to avoid rare issues that may occur; this is not a requirement by design so it could be removed in the future. - Never use custom functions when native variants are available; this makes sure fixes on the extension level also apply to your presences. You're free to use whatever you need if you do not find them listed in the docs.
- It is forbidden to code presences for a site without adding support to its primary language (for e.g., a YouTube presence coded with support only for Portueguese and Japanese, but not English itself.)
- The
smallImageKeyandsmallImageTextfields are intended to provide additional/secondary context (such asplaying/pausedfor video sites,browsingfor regular sites, and other cases) not to promote Discord profiles or anything unrelated to PreMiD. - You are not allowed to access
localStorage. - When accessing cookies for stored data, please prefix the key with
PMD_. - You may only make HTTP/HTTPS requests to
premid.appor the presence website API. If you are using external domains, you will be required to explain why it is necessary. - Do not set fields in the presence data object to undefined after it has been declared, use the
deletekeyword instead. (for e.g., usedelete data.startTimestampinstead ofdata.startTimestamp = undefined) - You are not allowed to write presences that change the functionality of a given website. This includes the addition, deletion, or modification of DOM elements.
¶ tsconfig.json
Do not write your own
tsconfig.jsonfile, use what has been provided on documentation.
¶ Modification
You must change the version in the metadata to be a higher value from the previous version when making changes to either the presence.ts, iframe.ts or metadata.json.
In some situations, presences may behave unexpectedly or could use some minor changes to improve their functionality. Here is a list of rules that you must follow while modifiying presences.
- You are not allowed to rewrite a presence or change its author. If the presence author was banned from the official server or hasn't made the required changes within a month, you may contact a reviewer to see if you can to rewrite the presence.
- If you make modifications to a presence and change at least a quarter of the presence's codebase, you are allowed to add yourself as a contributor. Contact a verifier for more information about this subject. - If you make modifications to a presence and change at least a quarter of the presence's codebase, you are allowed to add yourself as a contributor. Contact a reviewer for more information about this subject.
- Anyone may provide hotfixes to fix bugs; however, do not to make changes that are not required. Valid modifications include general fixes (code and typos), additions (descriptions and tags), missing files, etc. Do not change images if they are not outdated and are in specifications.
¶ Verification
All code contributed to the store will be licensed under the
Mozilla Public License 2.0.
If you need to contact someone, please use our official Discord server. All reviewers will have the
Reviewerrole on their profile.
Please keep in mind that the reviewers work voluntarily and manage other repositories in addition to this one, your pull request may not get reviewed until hours or even days after it has been created.
Always have an up-to-date fork before creating your pull request. This will help limit false positives from the checks.
The most important process of presence development is getting your presence on the store. This is done by making a pull request on GitHub on the PreMiD/Presences repository. Our reviewers will confirm that your presence is up to standards and will push it onto the store.
¶ Restrictions
Repetitive offenses such as breaking guidelines, spamming pull requests, threats, or innapropriate behavior will get you banned from creating presences.
In this scenerio, the following changes will occur:
- Presences under your management will be transferred to the PreMiD bot or another user (reviewer decision). The application id for each presence will be recreated under the new owner's name.
- All of your issues and pull requests (presence creation, presence contribution, etc) created following the ban will be prompty closed.
- Tickets created under your name regarding presence development will be deleted.
¶ Reviewing
A few things you should know after opening a pull request:
- It takes 2 reviewers to merge a pull request.
- If a pull request is inactive for a period of 14 days, it will be promptly closed.
- All checks must be passed in order to merge.
- ⚠️ You must provide new, unaltered screenshots (taken by you) showing a side-by-side comparison of your profile and the website to prove that your presence works. You are allowed to stitch screenshots together for viewing pleasure. This applies for both creation and modification.
- ⚠️ You are also required to include screenshots of the presence settings in the extension if supplied. An example can be seen here.
¶ Checks
Currently, a presence goes through 2 separate stages of checks. All of these checks help the reviewers determine whether your presence is suitable for deployment.
Codacyis a bot that checks for code quality. If you ever receive errors for new issues, you are required to fix them.Schema Validationwill scan yourmetadata.jsonfile for any errors (for e.g., missing fields, invalid value types, etc.). If you ever see any new issues, you are also required to fix those. Adding a schema field to yourmetadata.jsonfile will allow your text editor (if supported) to show you these errors during development.
¶ Additional Rules
- Always make sure to start your presence in the most appropriate folder, if its name starts with any Latin letter then it must be under its alphabetical match (for e.g.,
D/dアニメストアorG/Google). Any other Unicode/non-Latin characters must be under the#folder (for e.g.,#/巴哈姆特) and numbers under the0-9folder (for e.g.,0-9/4anime).
After meeting all of the guidelines with the proper reviews and checks, your presence will be merged with the store.
¶ Contributions
Revision 2 of the guidelines was written and was contributed to by the following individuals:
Revision 1 was maintained by the following individuals:
