Skip to content

contributing.md

Latest commit

 

History

History
156 lines (126 loc) · 5.2 KB

contributing.md

File metadata and controls

156 lines (126 loc) · 5.2 KB

Contributing

👍🎉 First off, thanks for taking the time to contribute! 🎉👍

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to electron@github.com.

The following is a set of guidelines for contributing to electron-apps. These are just guidelines, not rules. Use your best judgment and feel free to propose changes to this document in a pull request.

Adding your app

If you have an Electron application you'd like to see added, please open a pull request! All that's required is a basic YML file and a PNG icon.

Using the wizard 🔮

This repository has a CLI wizard much like npm init that you can use to generate a YML datafile for your app. To use the wizard, fork and clone this repository, then run:

git clone https://github.com/electron/electron-apps
cd electron-apps
npm install && npm run wizard

Adding your app by hand 💪

Another easy way to add a new app is to copy an existing app and edit its metadata.

To do so, create a new directory in the apps directory and include a .yml file and .png icon file. The directory can only contain numbers, lowercase letters, and dashes, and the yml and icon files should be named like so:

apps
└── my-cool-app
    ├── my-cool-app-icon.png
    └── my-cool-app.yml

YML file rules:

  • name is required.
  • description is required.
  • website is required, and must be a fully-qualified URL.
  • category is required and must be one of the following values:
    • Books
    • Business
    • Catalogs
    • Developer Tools
    • Education
    • Entertainment
    • Finance
    • Food & Drink
    • Games
    • Health & Fitness
    • Graphics & Design
    • Lifestyle
    • Kids
    • Magazines & Newspapers
    • Medical
    • Music
    • Navigation
    • News
    • Photo & Video
    • Productivity
    • Reference
    • Shopping
    • Social Networking
    • Sports
    • Travel
    • Utilities
  • repository is optional, but must be a fully-qualified URL if provided.
  • keywords is optional, but should be an array if provided.
  • license is optional.
  • screenshots are optional, but should be an array in the following format if provided: 
    screenshots:
    -
        imageUrl: 'https://mysite/awsome.png'
        caption: 'Awesome screenshot'
        imageLink: 'https://mysite/awesome.html'
    • imageUrl - required - fully-qualified URL of screenshot image. Allowed image types are png, jpg, and gif.
    • caption - an optional caption to display with the screenshot.
    • imageLink - an optional link URL to indicate the link that should be directed to when someone clicks on an image. If this field is not specified, clicking on a screenshot will go to the application website.
  • No fields should be left blank.

Icon file rules:

  • Must be a .png
  • Must be a square
  • Must be at least 256px by 256px
  • Must not be a copy of another company's or application's icon (see submission guidelines below)

Locales

By default, your app is assumed to be designed for English speakers. If your app supports a different language (or multiple languages), please add a locales property that lists all locales supported.

Example:

name: fangyuanjian
description: 'collaboration and messaging for small-to-medium sized businesses.'
website: 'http://bzsns.cn/'
keywords:
    - messaging
    - collaboration
locales:
  - zh-CN

Submission Guidelines

Some things to keep in mind when preparing your app for submission. Heavily inspired by the awesome-electron submission guidelines.

  • The pull request should have a useful title and include a link to the thing you're submitting and why it should be included.
  • Don't use another company's trademarks (icon, logo or name) without supplying evidence of prior permission
  • If you just created something, wait at least 20 days before submitting.
  • If you're submitting a closed source app, include evidence of it being built with Electron.
  • Submitted open source apps should have a readme, screenshot of the app in the readme, and a binary for at least one OS, preferably macOS, Linux and Windows.
  • Keep descriptions short and simple, but descriptive.
  • Start the description with a capital and end with a full stop/period.
  • Don't mention Electron in the description as it's implied.
  • Don't start the description with A or An.
  • Check your spelling and grammar.

Development

To develop this thing locally, there are a few things you should know:

You'll need a GitHub token to run the build task. Put it in a file named .env. It will be ignored by git.

cp .env.example .env

Testing

On Travis CI, the npm test command is run, which only tests human-submitted data.

When cutting a new release (which is normally done automatically by a Heroku scheduler process), the npm run test-all command is run, which tests not only the human-submitted data, but also the artifacts generated by the build process, like resized icons, icon color palettes, releases data, etc.