Mailspring/packages/client-app/CONTRIBUTING.md

102 lines
4.1 KiB
Markdown
Raw Normal View History

2015-10-30 07:56:16 +08:00
# Filing an Issue
2015-10-03 04:04:31 +08:00
Thanks for checking out N1! If you have a feature request, be sure to check out the [open source roadmap](http://trello.com/b/hxsqB6vx/n1-open-source-roadmap). If someone has already requested
the feature you have in mind, you can upvote the card on Trello—to keep things organized, we
often close feature requests on GitHub after creating Trello cards.
2015-10-03 04:04:31 +08:00
If you've found a bug, try searching for similars issue before filing a new one. Please include
the version of N1 you're using, the platform you're using (Mac / Windows / Linux), and the
type of email account. (Gmail, Outlook 365, etc.)
2015-10-03 04:04:31 +08:00
2015-10-30 07:56:16 +08:00
# Contributing to N1
2015-10-03 04:04:31 +08:00
The hosted sync engine allows us to control adoption of N1 and maintain a great
experience for our users. However, the sync engine is
2015-10-30 07:58:46 +08:00
[open source](https://github.com/nylas/sync-engine) and you can set it
up yourself to begin using N1 immediately. Follow instructions on the [sync
engine](https://github.com/nylas/sync-engine) repository.
2015-10-30 07:56:16 +08:00
### Getting Started
2015-10-03 04:04:31 +08:00
Before you get started, make sure you've installed the following dependencies.
N1's build scripts and tooling use modern JavaScript features and require:
- Node 6.0 or above with npm3
- python 2.7
Linux users should make sure they've installed all the packages listed at
https://github.com/nylas/nylas-mail/blob/master/.travis.yml#L10. Linux users on
Debian 8 and Ubuntu 15.04 onward must also install libgcrypt11 and gnome-keyring.
Next, clone and build N1 from source:
2015-10-03 04:04:31 +08:00
git clone https://github.com/nylas/nylas-mail.git
cd nylas-mail
2015-10-03 04:04:31 +08:00
script/bootstrap
Read the [getting started guides](https://nylas.github.io/N1/getting-started/).
2015-10-03 09:48:34 +08:00
**Building Nylas on Windows? See the [Windows instructions.](https://github.com/nylas/nylas-mail/blob/master/docs/Windows.md)**
2015-10-30 07:56:16 +08:00
### Running N1
2015-10-03 04:04:31 +08:00
build(*): electron-compile, electron-packager instead of custom tooling Summary: This diff removes significant cruft from N1's compilation and build tooling: - Electron-Packager replaces most of the code in build/tasks/* used to copy things, bundle things, download electron, etc. - script/bootstrap has been replaced with a much simpler script that does not use APM, does not download Electron (we just use electron as an NPM dep) and does not manully compile sqlite. It requires NPMv3, but I think that's safe. - babel and eslint are now devDependencies of the main project. The main project also supports optionalDependencies now. - npm test and npm start replace ./N1.sh - APM is still around, and is only put into N1 so it can install plugins at runtime. It should be removed as soon as we notify package maintainers and have them provide zips. - N1 no longer has it's own compile-cache or babel/typescript/coffeescript compilers. It delegates to electron-compile and electron-compilers. Both of these packages had to be forked and modified slightly, but I'm hopeful the modifications will make it back in to the projects and you can still consult their documentation for more info. + In the near future, I think we should stop shipping electron-compilers with N1. This would mean that all plugins would need to be compiled on pre-publish, just like NPM packages, and would complicate the local development story a bit, but would make the app smaller. electron-compile is not supposed to compile at runtime in the prod app, just pull from the compile cache. - I've re-organized Grunt according to Grunt best practices, where each tasks/* file specifies it's own config and imports grunt tasks. - Unfortunately, I was not able to use any open source projects for the deb and rpm builds, because we have things like postinst hooks and start menu items which are not supported by the electron installer-generators. WIP Turn off all LESS compilation, because themes. Doh. Use Grunt for new build process too, just remove tasks More changes Add babel-eslint Remove unused react-devtools WIP Add name Ignore nonexistent Switch to more modern approach to config for grunt Move zipping to mac installer task Restructure publish task so it aggregates first, can log useful info if publishing is disabled Fix build dirs Fix win installer Fix linux installer Fix linux installer Try making linux A few more Updates Upadtes fixes fixes Get rid of non-meaningful variables Resolve assets path Insert nylas.sh Clean up args more Actually use description Fix display name ugh More tweaks Expliclty write /usr/bin/nylas Improve vars Use old nylas.sh Reinstate APM to better scope this diff Test Plan: Test on Mac, Windows, Linux Reviewers: evan, jackie, juan Reviewed By: jackie, juan Differential Revision: https://phab.nylas.com/D3411
2016-11-10 05:50:46 +08:00
npm start
2015-10-03 04:04:31 +08:00
2015-10-30 07:56:16 +08:00
### Testing N1
2015-10-03 04:04:31 +08:00
build(*): electron-compile, electron-packager instead of custom tooling Summary: This diff removes significant cruft from N1's compilation and build tooling: - Electron-Packager replaces most of the code in build/tasks/* used to copy things, bundle things, download electron, etc. - script/bootstrap has been replaced with a much simpler script that does not use APM, does not download Electron (we just use electron as an NPM dep) and does not manully compile sqlite. It requires NPMv3, but I think that's safe. - babel and eslint are now devDependencies of the main project. The main project also supports optionalDependencies now. - npm test and npm start replace ./N1.sh - APM is still around, and is only put into N1 so it can install plugins at runtime. It should be removed as soon as we notify package maintainers and have them provide zips. - N1 no longer has it's own compile-cache or babel/typescript/coffeescript compilers. It delegates to electron-compile and electron-compilers. Both of these packages had to be forked and modified slightly, but I'm hopeful the modifications will make it back in to the projects and you can still consult their documentation for more info. + In the near future, I think we should stop shipping electron-compilers with N1. This would mean that all plugins would need to be compiled on pre-publish, just like NPM packages, and would complicate the local development story a bit, but would make the app smaller. electron-compile is not supposed to compile at runtime in the prod app, just pull from the compile cache. - I've re-organized Grunt according to Grunt best practices, where each tasks/* file specifies it's own config and imports grunt tasks. - Unfortunately, I was not able to use any open source projects for the deb and rpm builds, because we have things like postinst hooks and start menu items which are not supported by the electron installer-generators. WIP Turn off all LESS compilation, because themes. Doh. Use Grunt for new build process too, just remove tasks More changes Add babel-eslint Remove unused react-devtools WIP Add name Ignore nonexistent Switch to more modern approach to config for grunt Move zipping to mac installer task Restructure publish task so it aggregates first, can log useful info if publishing is disabled Fix build dirs Fix win installer Fix linux installer Fix linux installer Try making linux A few more Updates Upadtes fixes fixes Get rid of non-meaningful variables Resolve assets path Insert nylas.sh Clean up args more Actually use description Fix display name ugh More tweaks Expliclty write /usr/bin/nylas Improve vars Use old nylas.sh Reinstate APM to better scope this diff Test Plan: Test on Mac, Windows, Linux Reviewers: evan, jackie, juan Reviewed By: jackie, juan Differential Revision: https://phab.nylas.com/D3411
2016-11-10 05:50:46 +08:00
npm test
2015-10-03 04:04:31 +08:00
This will run the full suite of automated unit tests. We use [Jasmine 1.3](http://jasmine.github.io/1.3/introduction.html).
It runs all tests inside of the `/spec` folder and all tests inside of
`/internal_packages/**/spec`
You may skip certain tests (temporarily) with `xit` and `xdescribe`, or focus on only certain tests with `fit` and `fdescribe`.
### Linting N1
N1 lints clean against eslint, coffeelint, csslint, lesslint, and our own internal
tool, nylaslint. To run the linters, just run `npm run lint`.
2015-10-30 07:58:46 +08:00
### Creating binaries
Once you've checked out N1 and run `script/bootstrap`, you can create a packaged
version of the application by running `script/build`. Note that the builds
available at [https://nylas.com/N1](https://nylas.com/N1) include licensed
fonts, sounds, and other improvements. If you're just looking to run N1, you
should download it there!
# Pull requests
We require all authors sign our [Contributor License
Agreement](https://www.nylas.com/cla.html) before pull requests (even
minor ones) can be accepted. (It's similar to other projects, like NodeJS
Meteor, or React). I'm really sorry, but Legal made us do it.
2015-10-30 07:58:46 +08:00
### Commit Format
We decided to not impose super strict commit guidelines on the community.
We're trusting you to be thoughtful, responsible, committers.
We do have a few heuristics:
- Keep commits fairly isolated. Don't jam lots of different functionality
in 1 squashed commit. `git bisect` and `git cherry-pick` should still be
reasonable things to do.
- Keep commits fairly significant. DO `squash` all those little file
changes and "fixmes". Don't make it difficult to browse our history.
Play the balance between this idea and the last point. If a commit
doesn't deserve your time to write a long thoughtful message about, then
squash it.
- Be hyper-descriptive in your commit messages. I care less about what
you did (I can read the code), **I want to know WHY you did it**. Put
that in the commit body (not the subject). Itemize the major semantic
changes that happened.
- Read "[How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/)" if you haven't already (but don't be too prescriptivist about it!)
# Running Against Open Source Sync Engine
See [Configuration](https://github.com/nylas/nylas-mail/blob/master/CONFIGURATION.md)