¶ Guidelines
When publishing Presences to the Presences repository, we require you to follow a set of guidelines. To some, these strict rules may seem harsh. However, the implementation of these rulesets will keep us and the users from running into any 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.)
- 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 and must have some features other than just showing album/song title, etc.
- Presences are not allowed to run JS code with their own function to get variables. If Firefox has issues with built-in function inside
Presenceclass, you are allowed to do your own function and you need to tell us about it in Pull Request description. - 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).
- Presences for services like Discord Bot/Server Lists must follow these extra requirements:
- The domain should be at least 6 months old.
- Unique visitors per day:
- For 6 to 12 month old domains: 20,000 unique visitors/day.
- For 12+ month old domains: 45,000 unique visitors/day.
- The website can't be on a cheap domain like
.xyz,.cluband so on. - The website itself must have a very good quality, design, etc.
- Presences should use common details (strings starting with "general."). You can achieve this using
multiLanguagewith the provided strings. If your presence requires custom strings, then you shouldn't usemultiLanguageuntil the presence gets 1000 users. You can find an example here. - 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.ts
└── tsconfig.json
or if you're using a iframe.ts file:
presence
├── dist
│ └── metadata.json
├── 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.7",
"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,
"readLogs": false,
"settings": [
{
"id": "multiLanguage",
"multiLanguage": true
}
{
"id": "ID",
"title": "DISPLAY TITLE",
"icon": "FONTAWESOME ICON",
"value": true
},
{
"id": "ID",
"if": {
"ID": true
},
"title": "DISPLAY TITLE",
"icon": "FONTAWESOME ICON",
"value": "\"%song%\" by %artist%",
"placeholder": "use %song% or %artist%"
},
{
"id": "ID",
"title": "DISPLAY TITLE",
"icon": "FONTAWESOME ICON",
"value": 0,
"values": ["1", "2", "etc."]
}
]
}
If a field is listed as optional on the documentation or there is a
*next to the key, and your presence uses the default value for it, do not include it in themetadatafile. (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.) - If service has some explicit branding rules of their name, you should follow them.
¶ *altnames
- Only use this in scenarios where a website goes under multiple official names (e.g. Pokémon and 포켓몬스터). 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:
<MAJOR>.<MINOR>.<PATCH>. 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 resolution of
512x512pixels. You can resize it using a tool like imageresizer.
¶ 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.
¶ readLogs
- Must be
booleanvalue (e.g.trueorfalse). - Enables logs for your presence.
¶ warning
- Enables warning icon for prompting user that this presence needs more steps than only adding presence.
- Example of presence using this metadata variable is
VLC.
¶ 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 the 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. - If you are using the
multiLanguageoption it can have the following types:- Boolean type which will only enable strings from
general.jsonfrom the Localization repo or from the presence file (e.g. when the name of the presence is YouTube, the extension will get strings fromyoutube.jsontoo.) - String type (e.g.
youtube) which will specify the name of the files that you want to get strings from. - Array type (e.g.
["youtube", "discord"]) which will specify the name of the files that you want to get strings from.
- Boolean type which will only enable strings from
¶ 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.
TypeScript Plugin Recommendations for Strict Type Checking.
ESlint Recommendations.
Prettier.
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. Only allowed API to make request isFetch API. - Do not set fields in the presenceData 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.
- Presences that use buttons should follow extra requirements:
- Redirects to main page are prohibited.
- Promoting websites by them is prohibited.
- They can't display information you couldn't fit in other fields.
- Redirecting directly to audio/video stream is prohibited.
¶ 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.
- If the presence author hasn't been contactable in over a month, you may contact a reviewer to see if you can modify 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 reviewer for more information about this subject.
- Anyone may create PRs to fix bugs. 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 scenario, 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 7 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 3 separate stages of checks. All of these checks help the reviewers determine whether your presence is suitable for deployment.
DeepScanis a bot that checks for code quality. If you ever receive errors for new issues, you are required to fix them. Warning: DeepScan doesn't always give you errors. Please look at CodeFactor warnings instead.CodeFactoris 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.
¶ Suggestions
If you have some suggestions about our guidelines, you should contact us @ PreMiD's Discord server and we will check them!
¶ Contributions
Revision 3 of the guidelines was written and was contributed to by the following individuals:
Revision 2 of the guidelines was written and was contributed to by the following individuals:
Revision 1 was maintained by the following individuals:
