Update CONTRIBUTING and README, drop issue label bot

This commit is contained in:
Jason C. McDonald 2021-02-08 14:55:15 -08:00
parent ddbeb5452d
commit 573cc5aa02
4 changed files with 167 additions and 153 deletions

View file

@ -1,4 +0,0 @@
label-alias:
bug: 'bug'
feature_request: 'enhancement'
question: 'question'

View file

@ -1,32 +1,70 @@
# Contributing to Mailspring
Thanks for checking out Mailspring! We'd love for you to contribute. Whether you're a first-time open source contributor or an experienced developer, there are ways you can help make Mailspring great:
Thanks for checking out Mailspring! We'd love for you to contribute. Whether
you're a first-time open source contributor or an experienced developer, there
are ways you can help make Mailspring great!
1. Grab an issue tagged with **[Help Wanted](https://github.com/Foundry376/Mailspring/labels/help%20wanted)** and dig in! We try to add context to these issues when adding the label so you know where to get started in the codebase. Be wary of working on issues without the **Help Wanted** label - just because someone has created an issue doesn't mean we'll accept a pull request for it. See [Where to Contribute](#where-to-contribute) below for more information.
## Contributing Code
2. Triage issues that haven't been addressed. With a large community of users on many platforms, we have trouble keeping up GitHub issues and moving the project forward at the same time. If you're good at testing and addressing issues, we'd love your help!
One of the best ways is to grab a
[bug report](https://community.getmailspring.com/c/bugs/10),
[sync issue](https://community.getmailspring.com/c/sync/22),
or [feature suggestion](https://community.getmailspring.com/c/features/12)
that has been marked `accepted` and dig in. You can especially look for issues
marked as `help-wanted` or `low-hanging-fruit`.
### Filing an Issue
Please be wary of working on issues *not* marked as `accepted`. Just because
someone has created an issue doesn't mean we'll accept a pull request for it.
See [Where to Contribute](#where-to-contribute) below for more information.
If you have a bug to report or a feature to suggest, you may do so on our [Discourse](https://community.getmailspring.com/). Please carefully follow all instructions in the template for the given type of
issue you're reporting.
We also ask that you search for existing issues, *including closed ones!* We're in the process of migrating
our issues to [Discourse](https://community.getmailspring.com/). If someone has already requested the feature you have in mind, upvote it using the "Add Reaction" feature - our team often looks for issues that have community support.
For bugs, please verify that you're running the latest version of Mailspring. If you file an issue without providing detail, we may close it without comment.
You can also help implement *any* feature by creating a **plugin** for it!
If you need inspiration, you can dig through the list of
[feature suggestions](https://community.getmailspring.com/c/features/12),
especially looking for anything marked `for-plugin`.
### Pull requests
The first time you submit a pull request, a bot will ask you to sign a standard, bare-bones Contributor License Agreement. The CLA states that you waive any patent or copyright claims you might have to the code you're contributing. (e.g.: you can't submit a PR and then sue Mailspring for using your code.)
The first time you submit a pull request, a bot will ask you to sign a
standard, bare-bones Contributor License Agreement. The CLA states that you
waive any patent or copyright claims you might have to the code you're
contributing. (For example, you can't submit a PR and then sue Mailspring
for using your code.)
## Triaging Issues
Another way to help is to [answer questions](https://community.getmailspring.com/c/help/7),
or to triage [bug reports](https://community.getmailspring.com/c/bugs/10) and
[sync issues](https://community.getmailspring.com/c/sync/22). If you're good at
testing and addressing issues, we'd love your help!
## Filing Issues
If you have a bug to report or a feature to suggest, you may do so on our
[Discourse](https://community.getmailspring.com/). Please carefully follow all
instructions in the template for the given type of issue you're reporting.
We also ask that you search for existing issues, *including closed ones!*
We're in the process of migrating. If someone has already reported a bug or
requested the feature you have in mind, **vote for it** at the top.
Higher voted issues are more likely to be addressed.
For bugs, please verify that you're running the latest version of Mailspring.
If you file an issue without providing detail, we may close it without comment.
**Under no circumstances should you report an issue via GitHub. The GitHub
Issues feature is exclusively for Mailspring contributors to track tasks
which have been diagnosed, accepted, and scheduled on the roadmap.**
# Build and Run From Source
If you want to understand how Mailspring works or want to debug an issue, you'll want to get the source, build it, and run it locally.
If you want to understand how Mailspring works or want to debug an issue,
you'll want to get the source, build it, and run it locally.
### Installing Prerequisites
## Installing Prerequisites
You'll need git and a recent version of Node.JS (any v7.2.1+ is recommended with npm v3.10.10+). [nvm](https://github.com/creationix/nvm) is also highly recommended. Based on your platform, you'll also need:
You'll need git and a recent version of Node.JS (any v7.2.1+ is recommended
with npm v3.10.10+). [nvm](https://github.com/creationix/nvm) is also highly
recommended. Based on your platform, you'll also need:
**Windows:**
@ -35,7 +73,8 @@ You'll need git and a recent version of Node.JS (any v7.2.1+ is recommended with
**OS X:**
- Python
- Xcode and the Command Line Tools (Xcode -> Preferences -> Downloads), which will install `gcc` and the related toolchain containing `make`.
- Xcode and the Command Line Tools (Xcode -> Preferences -> Downloads), which
will install `gcc` and the related toolchain containing `make`.
**Linux:**
@ -46,7 +85,8 @@ You'll need git and a recent version of Node.JS (any v7.2.1+ is recommended with
- On Debian-based Linux: `sudo apt-get install libx11-dev libxkbfile-dev execstack libgconf-2-4 libsecret-1-dev`
- On Red Hat-based Linux: `sudo yum install libX11-devel.x86_64 libxkbfile-devel.x86_64 libsecret-1-dev libsecret-devel`.
After you have these tools installed, run the following commands to check out Mailspring,install dependencies, and launch the app:
After you have these tools installed, run the following commands to check out
Mailspring,install dependencies, and launch the app:
```
git clone https://github.com/foundry376/mailspring
@ -55,53 +95,87 @@ npm install
npm start
```
# Development Workflow
## Development Workflow
#### App Data
### App Data
When you're running Mailspring with `npm start`, it runs with the `--dev` flag and user data is located in a `Mailspring-dev` folder alongside the regular settings folder:
When you're running Mailspring with `npm start`, it runs with the `--dev` flag
and user data is located in a `Mailspring-dev` folder alongside the regular
settings folder:
- Mac: `~/Library/Application Support/Mailspring-dev`
- Windows: `C:\Users\<you>\AppData\Roaming\Mailspring-dev`
- Linux: `~/.config/Mailspring-dev/`
#### Developer Tools
### Developer Tools
From Mailspring, you can open the Developer Tools from the menu: `Menu > Developer > Toggle Developer Tools`. Here are a few tips for getting started:
From Mailspring, you can open the Developer Tools from the
menu: `Menu > Developer > Toggle Developer Tools`. Here are a few tips for
getting started:
- Errors and warnings will show in the console.
- On the console, `$m` is a shorthand for `mailspring-exports`, and allows you to access global `Stores` and `Model` classes.
- On the console, `$m` is a shorthand for `mailspring-exports`, and allows you
to access global `Stores` and `Model` classes.
- You don't need to stop and restart the development version of Mailspring after each change. You can just reload the window via `CMD+R` (`CTRL+R` on Windows, Linux).
- You don't need to stop and restart the development version of Mailspring
after each change. You can just reload the window via `CTRL+R` (Windows/Linux)
or `CMD+R` (macOS).
#### Linting
### Linting
We use `prettier` and `eslint` for linting our sources. You can run both of these by running `npm run lint` on the command line. Always do this before submitting a pull request to ensure the CI servers accept your code.
We use `prettier` and `eslint` for linting our sources. You can run both of
these by running `npm run lint` on the command line. Always do this before
submitting a pull request to ensure the CI servers accept your code.
#### Documentation
### Documentation
Back in 2015 and 2016, the Nylas Mail team made a huge effort to document the codebase. The docs are still [available on GitHub pages](https://foundry376.github.io/Mailspring/), and are still largely relevant to Mailspring development.
Back in 2015 and 2016, the Nylas Mail team made a huge effort to document
the codebase. The docs are still
[available on GitHub pages](https://foundry376.github.io/Mailspring/), and are
still largely relevant to Mailspring development.
#### Discussion Etiquette
### Testing Localization
In order to keep the conversation clear and transparent, please limit discussion to English and keep things on topic with the issue. Be considerate to others and try to be courteous and professional at all times.
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](code_of_conduct.md)
#### Testing Localization
You can run the app in different localizations by passing a langauge code to Electron via `--lang=de`. To use this in conjunction `npm start`, you'll need to use the `--` argument forwarding syntax: `npm start -- --lang=de`.
You can run the app in different localizations by passing a langauge code to
Electron via `--lang=de`. To use this in conjunction `npm start`, you'll need
to use the `--` argument forwarding syntax: `npm start -- --lang=de`.
# Where to Contribute
Check out the full issues list for a list of all potential areas for contributions. Note that just because an issue exists in the repository does not mean we will accept a contribution to the core mail client for it. There are several reasons we may not accepts a pull requests, like:
Check out our [Discourse](https://community.getmailspring.com/) for all
potential areas for contributions. Note that just because a topic exists does
not mean we will accept a contribution to the core mail client for it. There
are several reasons we may not accepts a pull requests, like:
- **Maintainability** - We're _extremely_ wary of adding options and preferences for niche behaviors. Email is a wild west, and we can't afford to support every possible configuration. Our general rule is that the code complexity of adding a preference isn't worth it unless the user base is fairly evenly divided about the desired behavior. [We don't want to end up with this!](https://cloud.githubusercontent.com/assets/1037212/14989123/2a74e810-110b-11e6-8b5d-6f343bca712f.png)
- **Maintainability** - We're _extremely_ wary of adding options and preferences
for niche behaviors. Email is a wild west, and we can't afford to support
every possible configuration. Our general rule is that the code complexity
of adding a preference isn't worth it unless the user base is fairly evenly
divided about the desired behavior.
[We don't want to end up with this!](https://cloud.githubusercontent.com/assets/1037212/14989123/2a74e810-110b-11e6-8b5d-6f343bca712f.png)
- **User experience** - We want to deliver a lightweight and smooth mail client, so UX and performance matter a lot. If you'd like to change or extend the UI, consider doing it in a plugin or theme.
- **User experience** - We want to deliver a lightweight and smooth mail
client, so UX and performance matter a lot. If you'd like to change or
extend the UI, consider doing it in a plugin or theme.
- **Architectural** - The team and/or feature owner needs to agree with any architectural impact a change may make. Things like new extension APIs must be discussed with and agreed upon by the feature owner.
To improve the chances to get a pull request merged you should select an issue that is labelled with the help-wanted or bug labels. If the issue you want to work on is not labelled with help-wanted or bug, you can start a conversation with the issue owner asking whether an external contribution will be considered.
- **Architectural** - The team and/or feature owner needs to agree with any
architectural impact a change may make. Things like new extension APIs must
be discussed with and agreed upon by the feature owner. To improve the
chances to get a pull request merged you should select an issue that is
labelled with the help-wanted or bug labels.
In short, if the issue you want to work on is not labelled with `accepted`, you
can start a conversation on the Discourse topic about whether an external
contribution will be considered.
# Code of Conduct
In order to keep the conversation clear and transparent, please limit
discussion to English and keep things on topic with the issue. Be considerate
to others and try to be courteous and professional at all times.
Please note that this project is released with a Contributor Code of Conduct.
By participating in this project you agree to abide by its terms.
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](code_of_conduct.md)

View file

@ -7,17 +7,25 @@
Mailspring's UI is open source (GPLv3) and written in TypeScript with [Electron](https://github.com/atom/electron) and [React](https://facebook.github.io/react/) - it's built on a plugin architecture and was designed to be easy to extend. Check out [CONTRIBUTING.md](https://github.com/Foundry376/Mailspring/blob/master/CONTRIBUTING.md) to get started!
Mailspring's sync engine is spawned by the Electron application and runs locally on your computer. It will be open-sourced in the future but is [currently closed source.](https://github.com/Foundry376/Mailspring/blob/master/ROADMAP.md#why-is-mailsync-closed-source) When you set up your development environment, Mailspring uses the latest version of the sync process we've shipped for your platform so you don't need to pull sources or install its compile-time dependencies.
Mailspring's sync engine is spawned by the Electron application and runs locally on your computer. [It is open source (GPLv3) and written in C++ and C.](https://github.com/Foundry376/Mailspring-Sync) For convenience, however, when you set up your development environment, Mailspring uses the latest version of the sync engine we've shipped for your platform so you don't need to pull sources or install its compile-time dependencies.
![Mailspring Screenshot](https://github.com/Foundry376/Mailspring/raw/master/screenshots/hero_graphic_mac%402x.png)
## Features
Mailspring comes packed with powerful features like Unified Inbox, Snooze, Send Later, Mail Rules, Templates and more. Mailspring Pro, which you can unlock with a monthly subscription, adds even more features for people who send a ton of email: link tracking, read receipts, mailbox analytics, contact and company profiles. **All of these features run in the client - Mailspring does not send your email credentials to the cloud.** For a full list of features, check out [getmailspring.com](https://getmailspring.com/).
Mailspring comes packed with powerful features like Unified Inbox, Snooze, Send
Later, Mail Rules, Templates and more. Mailspring Pro, which you can unlock
with a monthly subscription, adds even more features for people who send a ton
of email: link tracking, read receipts, mailbox analytics, contact and company
profiles. **All of these features run in the client - Mailspring does not send
your email credentials to the cloud.** For a full list of features, check out
[getmailspring.com](https://getmailspring.com/).
## Download Mailspring
You can download compiled versions of Mailspring for Windows, Mac OS X, and Linux (deb, rpm and snap) from [https://getmailspring.com/download](https://getmailspring.com/download).
You can download compiled versions of Mailspring for Windows, Mac OS X, and
Linux (deb, rpm and snap) from
[https://getmailspring.com/download](https://getmailspring.com/download).
## Getting Help
@ -26,38 +34,63 @@ You can find community-based help and discussion with other Mailspring users on
## Contributing
Mailspring's UI is entirely open-source and pull requests and contributions are welcome! There are three ways to contribute: building a plugin, building a theme, and submitting pull requests to the project itself. When you're getting started, you may want to join our [Discourse](https://community.getmailspring.com/) so you can ask questions and learn from other people doing development.
Mailspring's MailSync, however, is closed source. You can read more about the reasons why this is in the [roadmap](https://github.com/Foundry376/Mailspring/blob/master/ROADMAP.md#why-is-mailsync-closed-source).
Mailspring is entirely open-source. Pull requests and contributions are
welcome! There are three ways to contribute: building a plugin, building a
theme, and submitting pull requests to the project itself. When you're getting
started, you may want to join our
[Discourse](https://community.getmailspring.com/) so you can ask questions and
learn from other people doing development.
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md)
### Building A Plugin
Plugins lie at the heart of Mailspring and give it its powerful features. Building your own plugins allows you to integrate the app with other tools, experiment with new workflows, and more. Follow the [Getting Started guide](https://Foundry376.github.io/Mailspring/) to write your first plugin in five minutes.
Plugins lie at the heart of Mailspring and give it its powerful features.
Building your own plugins allows you to integrate the app with other tools,
experiment with new workflows, and more. Follow the [Getting Started
guide](https://Foundry376.github.io/Mailspring/) to write your first plugin in
five minutes.
- To create your own theme, check out the [Mailspring-Theme-Starter](https://github.com/Foundry376/Mailspring-Theme-Starter).
- To create your own theme, check out the
[Mailspring-Theme-Starter](https://github.com/Foundry376/Mailspring-Theme-Starter).
- To create your own plugin, check out the [Mailspring-Plugin-Starter](https://github.com/Foundry376/Mailspring-Plugin-Starter).
- To create your own plugin, check out the
[Mailspring-Plugin-Starter](https://github.com/Foundry376/Mailspring-Plugin-Starter).
A plugin "store" like the Chrome Web Store is coming soon, and will make it easy for other users to discover plugins you create. (Right now, users need to "sideload" the plugins into the app by downloading them and copying them into place.)
A plugin "store" like the Chrome Web Store is coming soon, and will make it
easy for other users to discover plugins you create. (Right now, users need to
"sideload" the plugins into the app by downloading them and copying them into
place.)
You can share and browse Mailspring Plugins, and discuss plugin development with other developers, on our
You can share and browse Mailspring Plugins, and discuss plugin development
with other developers, on our
[Discourse](https://community.getmailspring.com/).
### Building a Theme
The Mailspring user interface is styled using CSS, which means it's easy to modify and extend. Mailspring comes stock with a few beautiful themes, and there are many more which have been built by community developers. To start creating a theme, [clone the theme starter](https://github.com/Foundry376/Mailspring-Theme-Starter)!
The Mailspring user interface is styled using CSS, which means it's easy to
modify and extend. Mailspring comes stock with a few beautiful themes, and
there are many more which have been built by community developers. To start
creating a theme, [clone the theme starter](https://github.com/Foundry376/Mailspring-Theme-Starter)!
If you are updating an existing Nylas theme for Mailspring here is a [step by step tutorial](https://foundry376.zendesk.com/hc/en-us/articles/115001918391-How-do-I-update-an-N1-Nylas-Mail-theme-for-Mailspring-). Notice: as part of the update process you will probably need to [import mailspring base variables](https://github.com/Foundry376/Mailspring/issues/326#issuecomment-343757775).
If you are updating an existing Nylas theme for Mailspring here is a [step by
step tutorial](https://foundry376.zendesk.com/hc/en-us/articles/115001918391-How-do-I-update-an-N1-Nylas-Mail-theme-for-Mailspring-).
Notice: as part of the update process you will probably need to [import
mailspring base variables](https://github.com/Foundry376/Mailspring/issues/326#issuecomment-343757775).
You can share and browse Mailspring Themes, and discuss theme development with other developers, on our
[Discourse](https://community.getmailspring.com/).
You can share and browse Mailspring Themes, and discuss theme development with other developers, on our [Discourse](https://community.getmailspring.com/).
### Localizing / Translating
Mailspring 1.5.0 and above support localization. If you're a fluent speaker of another language, we'd love your help improving translations. Check out the [LOCALIZATION](https://github.com/Foundry376/Mailspring/blob/master/LOCALIZATION.md) guide for more information. You can discuss localization and translation with other developers on our [Discourse](https://community.getmailspring.com/).
Mailspring (1.5.0 and above) supports localization. If you're a fluent speaker of
another language, we'd love your help improving translations. Check out the
[LOCALIZATION](https://github.com/Foundry376/Mailspring/blob/master/LOCALIZATION.md)
guide for more information. You can discuss localization and translation with
other developers on our [Discourse](https://community.getmailspring.com/).
### Contributing to Mailspring Core
Pull requests are always welcome - check out [CONTRIBUTING](https://github.com/Foundry376/Mailspring/blob/master/CONTRIBUTING.md) for more information about setting up the development environment, running tests locally, and submitting pull requests.
Pull requests are always welcome - check out
[CONTRIBUTING](https://github.com/Foundry376/Mailspring/blob/master/CONTRIBUTING.md)
for more information about setting up the development environment, running
tests locally, and submitting pull requests.

View file

@ -1,89 +0,0 @@
## Roadmap:
The initial release of Mailspring was in Nov. 2017. The roadmap is largely based on popular GitHub issues plus the larger projects outlined here. For a complete list of features that have been shipped in the app, see the release notes in the changelog.
### Summer 2019 (Planned)
* **Calendar**
Goal: Build a beautiful CalDav and Google Calendar interface that can be opened in a new window or as a tab in the main window, making Mailspring a full replacement for the calendar-contacts-email suite.
### Spring 2019 (Planned)
* **Email Signing**
Goal: Allow users to sign outgoing email with a certificate, and verify the signatures of signed inbound email.
* **Mail Merge**
Goal: Make it possible to use a Template and a spreadsheet to batch-send emails with open / link tracking. Nylas Mail used to have this feature but the implementation confused users and didn't handle sending errors well. The new version will
* **Theme and Plugin Browser**
Goal: Make it easier to download and install community themes and plugins from a trusted, centralized "gallery", like the Chrome Web Store. (No immediate plans to allow to enable paid plugins.)
### Fall 2018
* **Localization**
Goal: Make underlying architectural changes that will allow Mailspring to be localized into dozens of languages. (Shipped in 1.5.0)
* **Electron 4**
Goal: Move Mailspring to a newer Electron release and make the necessary changes to support it.
### Summer 2018
* **Improved Search UI**
Goal: Highlight Mailspring's Gmail-style search features by overhauling the search bar. Allow users to save searches to the sidebar and right-click threads to "Search for more like this..." (Sihpped in 1.3.0)
* **macOS Touchbar Support**
Goal: Expose a broad set of touch bar actions that mirror options shown in Mailspring's UI and expand the app's menus to include all keyboard shortcuts. (Shipped in 1.4.0)
### Spring 2018
* **Thread Sharing**
Goal: Bring back the old Nylas Mail feature that allowed you to sync an email thread to the cloud and share it using a link. (Shipped in 1.2.0)
* **Overhauled Composer**
Goal: Replace Mailspring's custom contenteditable wrapper and it's many bugs with a standard JS library that is maintained on it's own, lowering the surface area we need to maintain for Mailspring. (Shipped SlateJS in 1.1.0)
* **New Template Editor**
Goal: Brand new template editor in _Preferences > Templates_ with a more streamlined UI based on the new composer. (Shipped in 1.1.0)
---
### Longer-term
* **Sync Issues**
Goal: Make it possible to connect and sync any IMAP account with Mailspring. The project is _close_ but still encounters sync issues with small or unsual IMAP providers.
* **Performance**
Goal: Users shouldn't notice Mailspring is an Electron app. Need to improve typing / load performance of the composer and continue improving responsiveness of the thread list and message list.
* **Advanced Mail Rules**
Goal: Create a new UI and revamp the mail rules engine to enable mail rules based on custom JavaScript code. Could enable really advanced workflows to be automated if we did it right!
* **Contact Management**
Goal: Replace Mailspring's built in contacts list (which is based on email headers) with one that uses CardDav and syncs with Google Contacts / O365 Contacts and allows full contact CRUD.
## Why is Mailsync Closed Source?
For the initial release I've decided to keep the new C++ codebase closed-source. When you pull this repository and run `npm install`, the correct Mailsync build for your platform is automatically downloaded and put in place so you can hack away on the Mailspring Electron app. For those of you who are interested, here's why it's closed-source:
* **Open source is a commitment.** When I was the lead engineer of the Nylas Mail team at Nylas, I spent thousands of hours responding to GitHub issues, helping people build the source, and trying to give PR feedback that was actionable and kind. I'm expecting to spend about 30% of my time working with the open-source community on the JavaScript side of Mailspring, and I'd rather focus on improving existing documentation and hackability than expand code surface area past what I can support. Especially until it's past the ["bus factor"](https://en.wikipedia.org/wiki/Bus_factor) of one!
* **Mailsync is hard to compile.** Mailsync is written in C++0x and uses new features like `shared_ptr` and `condition_variable`. It requires GCC 4.8 and has a ton of dependencies and required build flags. If `node-sqlite3` is any indication, open-sourcing it in it's current form would be a GitHub Issues disaster. (Compared to mailsync, `node-sqlite3` is pretty easy to build but a whopping _35%_ of it's open issues are [compilation-related!](https://github.com/mapbox/node-sqlite3/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20compile) 😰).
* **The odds of great PRs are low.** Mailsync is a multithreaded, cross-platform C++ application that interfaces with old, fragile protocols that have their own learning curves and are difficult to mock. For folks to contribute meaningful pull requests, I'd have to write great docs and tests. I'd also need to spend a /lot/ of time reviewing changes for side-effects, enforcing good C++ techniques, and checking changes for performance impact. Maybe I'll be able to support this in the future, but not yet!
If you're interested in contributing to the Mailspring Mailsync codebase and have some time and skill to throw at it, please let me know!