Ramiro Saenz
7 years ago
16 changed files with 429 additions and 64 deletions
@ -0,0 +1,271 @@ |
|||||||
|
# Contributor's Guide |
||||||
|
|
||||||
|
We welcome pull requests! Follow these steps to contribute: |
||||||
|
|
||||||
|
1. Find an [issue](https://github.com/saenzramiro/rambox/issues) that needs assistance. |
||||||
|
|
||||||
|
2. Let us know you are working on it by posting a comment on the issue. |
||||||
|
|
||||||
|
3. Follow the [Contribution Guidelines](#contribution-guidelines) to start working on the issue. |
||||||
|
|
||||||
|
Working on your first Pull Request? You can learn how from this *free* series [How to Contribute to an Open Source Project on GitHub] |
||||||
|
|
||||||
|
(https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github) |
||||||
|
|
||||||
|
###### If you've found a bug that is not on the board, [follow these steps](README.md#found-a-bug). |
||||||
|
|
||||||
|
-------------------------------------------------------------------------------- |
||||||
|
|
||||||
|
## Contribution Guidelines |
||||||
|
|
||||||
|
### Setup |
||||||
|
|
||||||
|
- [Prerequisites](#prerequisites) |
||||||
|
- [Forking the Project](#forking-the-project) |
||||||
|
- [Create a Branch](#create-a-branch) |
||||||
|
- [Set Up rambox](#set-up-rambox) |
||||||
|
|
||||||
|
### Create |
||||||
|
|
||||||
|
- [Make Changes](#make-changes) |
||||||
|
- [Run The Test Suite](#run-the-test-suite) |
||||||
|
|
||||||
|
### Submit |
||||||
|
|
||||||
|
- [Creating a Pull Request](#creating-a-pull-request) |
||||||
|
- [Common Steps](#common-steps) |
||||||
|
- [How We Review and Merge Pull Requests](#how-we-review-and-merge-pull-requests) |
||||||
|
- [How We Close Stale Issues](#how-we-close-stale-issues) |
||||||
|
- [Next Steps](#next-steps) |
||||||
|
- [Other Resources](#other-resources) |
||||||
|
|
||||||
|
### Prerequisites |
||||||
|
|
||||||
|
| Prerequisite | Version | |
||||||
|
| ------------------------------------------------------------- | ------- | |
||||||
|
| [Sencha](https://www.sencha.com/products/extjs/cmd-download/) | `=6.1.2.15` | |
||||||
|
| [Ruby](https://www.ruby-lang.org/en/downloads/) | `=2.3` | |
||||||
|
| [Node.js](http://nodejs.org) | `~ ^4.0.0` | |
||||||
|
| npm (comes with Node) | `~ ^3.8.7` | |
||||||
|
|
||||||
|
> _Updating to the latest releases is recommended_. |
||||||
|
|
||||||
|
If Node.js, ruby, or sencha cmd is already installed on your machine, run the following commands to validate the versions: |
||||||
|
|
||||||
|
```shell |
||||||
|
node -v |
||||||
|
ruby -v |
||||||
|
sencha |
||||||
|
``` |
||||||
|
|
||||||
|
If your versions are lower than the prerequisite versions, you should update. |
||||||
|
|
||||||
|
### Forking the Project |
||||||
|
|
||||||
|
#### Setting Up Your System |
||||||
|
|
||||||
|
1. Install [Git](https://git-scm.com/) or your favorite Git client. |
||||||
|
2. (Optional) [Setup an SSH Key](https://help.github.com/articles/generating-an-ssh-key/) for GitHub. |
||||||
|
|
||||||
|
#### Forking rambox |
||||||
|
|
||||||
|
1. Go to the top level rambox repository: <https://github.com/saenzramiro/rambox> |
||||||
|
2. Click the "Fork" Button in the upper right hand corner of the interface ([More Details Here](https://help.github.com/articles/fork-a-repo/)) |
||||||
|
3. After the repository (repo) has been forked, you will be taken to your copy of the rambox repo at <https://github.com/yourUsername/rambox> |
||||||
|
|
||||||
|
#### Cloning Your Fork |
||||||
|
|
||||||
|
1. Open a Terminal / Command Line / Bash Shell in your projects directory (_i.e.: `/yourprojectdirectory/`_) |
||||||
|
2. Clone your fork of rambox |
||||||
|
|
||||||
|
```shell |
||||||
|
$ git clone https://github.com/yourUsername/rambox.git |
||||||
|
``` |
||||||
|
|
||||||
|
**(make sure to replace `yourUsername` with your GitHub username)** |
||||||
|
|
||||||
|
This will download the entire rambox repo to your projects directory. |
||||||
|
|
||||||
|
#### Setup Your Upstream |
||||||
|
|
||||||
|
1. Change directory to the new rambox directory (`cd rambox`) |
||||||
|
2. Add a remote to the official rambox repo: |
||||||
|
|
||||||
|
```shell |
||||||
|
$ git remote add upstream https://github.com/saenzramiro/rambox.git |
||||||
|
``` |
||||||
|
|
||||||
|
Congratulations, you now have a local copy of the rambox repo! |
||||||
|
|
||||||
|
### Create a Branch |
||||||
|
|
||||||
|
Before you start working, you will need to create a separate branch specific to the issue / feature you're working on. You will push your work to this branch. |
||||||
|
|
||||||
|
#### Naming Your Branch |
||||||
|
|
||||||
|
Name the branch something like `fix/xxx` or `feature/xxx` where `xxx` is a short description of the changes or feature you are attempting to add. For example |
||||||
|
|
||||||
|
`fix/email-login` would be a branch where you fix something specific to email login. |
||||||
|
|
||||||
|
#### Adding Your Branch |
||||||
|
|
||||||
|
To create a branch on your local machine (and switch to this branch): |
||||||
|
|
||||||
|
```shell |
||||||
|
$ git checkout -b [name_of_your_new_branch] |
||||||
|
``` |
||||||
|
|
||||||
|
and to push to GitHub: |
||||||
|
|
||||||
|
```shell |
||||||
|
$ git push origin [name_of_your_new_branch] |
||||||
|
``` |
||||||
|
|
||||||
|
**If you need more help with branching, take a look at [this](https://github.com/Kunena/Kunena-Forum/wiki/Create-a-new-branch-with-git-and-manage-branches).** |
||||||
|
|
||||||
|
### Set Up rambox |
||||||
|
|
||||||
|
Once you have rambox cloned, before you start the application, you first need to install all of the dependencies: |
||||||
|
|
||||||
|
```bash |
||||||
|
# Install NPM dependencies |
||||||
|
npm install |
||||||
|
``` |
||||||
|
|
||||||
|
Then you need to add the private environment variables (API Keys): |
||||||
|
|
||||||
|
```bash |
||||||
|
# Copy `env-sample.js` with a name of env.js |
||||||
|
# Populate it with Auth0 clientid and domain e.g. test.auth0.com |
||||||
|
# You can get these details from one of your "apps" here https://manage.auth0.com/#/clients/ |
||||||
|
|
||||||
|
# macOS / Linux |
||||||
|
cp env-sample.js env.js |
||||||
|
|
||||||
|
# Windows |
||||||
|
copy env-sample.js env.js |
||||||
|
``` |
||||||
|
Then edit the `env.js` file and modify the API keys only for services that you will use. |
||||||
|
|
||||||
|
```bash |
||||||
|
# Compile the files... |
||||||
|
$ sencha app watch |
||||||
|
$ npm start # in a new terminal |
||||||
|
``` |
||||||
|
|
||||||
|
### Make Changes |
||||||
|
|
||||||
|
This bit is up to you! |
||||||
|
|
||||||
|
#### How to find the code in the rambox codebase to fix/edit |
||||||
|
|
||||||
|
The best way to find out any code you wish to change/add or remove is using |
||||||
|
the GitHub search bar at the top of the repository page. For example, you could |
||||||
|
search for a challenge name and the results will display all the files along |
||||||
|
with line numbers. Then you can proceed to the files and verify this is the area |
||||||
|
that you were looking forward to edit. Always feel free to reach out to the chat |
||||||
|
room when you are not certain of any thing specific in the code. |
||||||
|
|
||||||
|
#### Adding or Editing Services |
||||||
|
|
||||||
|
The services are stored inside the file `./app/store/ServicesList.js`. Add your service to the *BOTTOM* of the array. |
||||||
|
|
||||||
|
The logo it's referencing is located in `./resources/icons/`. |
||||||
|
|
||||||
|
To see these changes you'll need to stop your `npm start` and `sencha app watch`, and then rerun those. |
||||||
|
|
||||||
|
### Creating a Pull Request |
||||||
|
|
||||||
|
#### What is a Pull Request? |
||||||
|
|
||||||
|
A pull request (PR) is a method of submitting proposed changes to the rambox |
||||||
|
repo (or any repo, for that matter). You will make changes to copies of the |
||||||
|
files which make up rambox in a personal fork, then apply to have them |
||||||
|
accepted by rambox proper. |
||||||
|
|
||||||
|
#### Important: ALWAYS EDIT ON A BRANCH |
||||||
|
|
||||||
|
Take away only one thing from this document: Never, **EVER** |
||||||
|
make edits to the `staging` branch. ALWAYS make a new branch BEFORE you edit |
||||||
|
files. This is critical, because if your PR is not accepted, your copy of |
||||||
|
staging will be forever sullied and the only way to fix it is to delete your |
||||||
|
fork and re-fork. |
||||||
|
|
||||||
|
### Common Steps |
||||||
|
|
||||||
|
1. Once the edits have been committed, you will be prompted to create a pull |
||||||
|
request on your fork's GitHub Page. |
||||||
|
|
||||||
|
2. By default, all pull requests should be against the rambox main repo, `staging` |
||||||
|
branch. |
||||||
|
**Make sure that your Base Fork is set to saenzramiro/rambox when raising a Pull Request.** |
||||||
|
|
||||||
|
3. Submit a pull request. |
||||||
|
|
||||||
|
4. The title (also called the subject) of your PR should be descriptive of your |
||||||
|
changes and succinctly indicates what is being fixed. |
||||||
|
|
||||||
|
- **Do not add the issue number in the PR title or commit message.** |
||||||
|
|
||||||
|
- Examples: `Added Service servicename` `Correct typo in menu` |
||||||
|
|
||||||
|
5. In the body of your PR include a more detailed summary of the changes you |
||||||
|
made and why. |
||||||
|
|
||||||
|
- If the PR is meant to fix an existing bug/issue then, at the end of |
||||||
|
your PR's description, append the keyword `closes` and #xxxx (where xxxx |
||||||
|
is the issue number). Example: `closes #1337`. This tells GitHub to |
||||||
|
close the existing issue, if the PR is merged. |
||||||
|
|
||||||
|
6. Indicate if you have tested on a local copy of the site or not. |
||||||
|
|
||||||
|
### How We Review and Merge Pull Requests |
||||||
|
|
||||||
|
rambox has a team of volunteer Issue Moderators. These Issue Moderators routinely go through open pull requests in a process called [Quality Assurance] |
||||||
|
|
||||||
|
(https://en.wikipedia.org/wiki/Quality_assurance) (QA). |
||||||
|
|
||||||
|
1. If an Issue Moderator QA's a pull request and confirms that the new code does what it is supposed without seeming to introduce any new bugs, they will comment |
||||||
|
|
||||||
|
"LGTM" which means "Looks good to me." |
||||||
|
|
||||||
|
2. Another Issue Moderator will QA the same pull request. Once they have also confirmed that the new code does what it is supposed to without seeming to introduce |
||||||
|
|
||||||
|
any new bugs, they will merge the pull request. |
||||||
|
|
||||||
|
If you would like to apply to join our Issue Moderator team - which is a Core Team position - message [@BerkeleyTrue](https://gitter.im/berkeleytrue) with links |
||||||
|
|
||||||
|
to 5 of your pull requests that have been accepted and 5 issues where you have helped someone else through commenting or QA'ing. |
||||||
|
|
||||||
|
### How We Close Stale Issues |
||||||
|
|
||||||
|
We will close any issues or pull requests that have been inactive for more than 15 days, except those that match the following criteria: |
||||||
|
- bugs that are confirmed |
||||||
|
- pull requests that are waiting on other pull requests to be merged |
||||||
|
- features that are a part of a GitHub project |
||||||
|
|
||||||
|
### Next Steps |
||||||
|
|
||||||
|
#### If your PR is accepted |
||||||
|
|
||||||
|
Once your PR is accepted, you may delete the branch you created to submit it. |
||||||
|
This keeps your working fork clean. |
||||||
|
|
||||||
|
You can do this with a press of a button on the GitHub PR interface. You can |
||||||
|
delete the local copy of the branch with: `git branch -D branch/to-delete-name` |
||||||
|
|
||||||
|
#### If your PR is rejected |
||||||
|
|
||||||
|
Don't despair! You should receive solid feedback as to |
||||||
|
why it was rejected and what changes are needed. |
||||||
|
|
||||||
|
Many Pull Requests, especially first Pull Requests, require correction or |
||||||
|
updating. If you have used the GitHub interface to create your PR, you will need |
||||||
|
to close your PR, create a new branch, and re-submit. |
||||||
|
|
||||||
|
If you have a local copy of the repo, you can make the requested changes and |
||||||
|
amend your commit with: `git commit --amend` This will update your existing |
||||||
|
commit. When you push it to your fork you will need to do a force push to |
||||||
|
overwrite your old commit: `git push --force` |
||||||
|
|
||||||
|
Be sure to post in the PR conversation that you have made the requested changes. |
||||||
@ -1,6 +0,0 @@ |
|||||||
## To Do |
|
||||||
|
|
||||||
- Change theme. |
|
||||||
- Deeplink to add new service. |
|
||||||
- Dock Menu (http://electron.atom.io/docs/tutorial/desktop-environment-integration/#custom-dock-menu-os-x) |
|
||||||
- Crash Reporter. |
|
||||||
|
Before Width: | Height: | Size: 12 KiB After Width: | Height: | Size: 9.3 KiB |
|
After Width: | Height: | Size: 15 KiB |
|
Before Width: | Height: | Size: 68 KiB After Width: | Height: | Size: 3.2 KiB |
Loading…
Reference in new issue