Skip to content

Commit

Permalink
doc: update various markdown docs (#28)
Browse files Browse the repository at this point in the history 
* doc(contributing): improve text & formatting
* chore(issue-templates): update & improve
* docs(contributing): apply markdown format
  • Loading branch information
@erisu
erisu authored Sep 4, 2020
1 parent 826e3ae commit fe1cdf2
Show file tree
Hide file tree
Showing 4 changed files with 143 additions and 101 deletions.
160 changes: 85 additions & 75 deletions .github/CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,106 +2,116 @@

We love pull requests from everyone.

[Fork](https://help.github.com/articles/fork-a-repo/), then [clone](https://help.github.com/articles/cloning-a-repository/) the repo:
## How to Contribute

```
git clone git@github.com:your-username/phonegap-plugin-push.git
```
There are multiple ways to contribute:

Set up a branch for your feature or bugfix with a link to the original repo:
* Submit Issue Tickets (Bugs Reports)
* Improve Documentation
* Contribute Code

```
git checkout -b my-awesome-new-feature
git push --set-upstream origin my-awesome-new-feature
git remote add upstream /~https://github.com/phonegap/phonegap-plugin-push.git
```
## Setup for Contributing Codde

Set up the project:
Before we can start submitting code contributions, we setup locally a workspace where we can work on the code.

```
npm install
```
1. [Fork](https://help.github.com/articles/fork-a-repo/) this repo by following the GitHub's "[Fork a repo](https://help.github.com/articles/fork-a-repo/)" quickstart guide.
2. [Clone](https://help.github.com/articles/cloning-a-repository/) the newly forked repo locally.

Make sure the tests pass before changing anything:
```bash
git clone git@github.com:your-username/phonegap-plugin-push.git
```

```
npm test
```
## Make First Codde Contribution

Make your change. Add tests for your change. Make the tests pass:
1. Create a new branch where you will make your feature or bugfix changes, with a link to the original repo:

```
npm test
```
```bash
git checkout -b my-awesome-new-feature
git push --set-upstream origin my-awesome-new-feature
git remote add upstream /~https://github.com/havesource/cordova-plugin-push.git
```

Commit changes:
2. Install project dependencies

```
git commit -m "Cool stuff"
```
```bash
npm install
```

Consider starting the commit message with an applicable emoji:
* :art: `:art:` when improving the format/structure of the code
* :zap: `:zap:` when improving performance
* :non-potable_water: `:non-potable_water:` when plugging memory leaks
* :memo: `:memo:` when writing docs
* :ambulance: `:ambulance:` a critical hotfix.
* :sparkles: `:sparkles:` when introducing new features
* :bookmark: `:bookmark:` when releasing / version tags
* :rocket: `:rocket:` when deploying stuff
* :penguin: `:penguin:` when fixing something on Android
* :apple: `:apple:` when fixing something on iOS
* :checkered_flag: `:checkered_flag:` when fixing something on Windows
* :bug: `:bug:` when fixing a bug
* :fire: `:fire:` when removing code or files
* :green_heart: `:green_heart:` when fixing the CI build
* :white_check_mark: `:white_check_mark:` when adding tests
* :lock: `:lock:` when dealing with security
* :arrow_up: `:arrow_up:` when upgrading dependencies
* :arrow_down: `:arrow_down:` when downgrading dependencies
* :shirt: `:shirt:` when removing linter warnings
* :hammer: `:hammer:` when doing heavy refactoring
* :heavy_minus_sign: `:heavy_minus_sign:` when removing a dependency.
* :heavy_plus_sign: `:heavy_plus_sign:` when adding a dependency.
* :wrench: `:wrench:` when changing configuration files.
* :globe_with_meridians: `:globe_with_meridians:` when dealing with internationalization and localization.
* :pencil2: `:pencil2:` when fixing typos.
* :hankey: `:hankey:` when writing bad code that needs to be improved.
* :package: `:package:` when updating compiled files or packages.

Make sure your branch is up to date with the original repo:
3. Make sure that the tests are pass before and after making any changes:

```
git fetch upstream
git merge upstream/master
```
```bash
npm test
```

Review your changes and any possible conflicts and push to your fork:
4. After making changes and tests are passing, commit the changes:

```
git push origin
```bash
git commit -m "feat(android): my new cool feature"
```

❗ Make sure to follow the [Commit Message and PR Title Semantics](#Commit-Message-and-PR-Title-Semantics)

5. Push your commits to your fork:

```bash
git push origin
```

6. [Submit a pull request](https://help.github.com/articles/creating-a-pull-request/).

## Commit Message and PR Title Semantics

When writting a commit message or title to a PR, please make sure to follow the convention described below to help use understand what is being reviewed. The semantics will be validated automatticly by a semantic checker.

### `Types`

There are various `types` of commits that can be choosed from. The following `types`, described below, should be used when writting a commit message to help us understand the type of changes we are reviewing.

* `ci:` - When change are made to the CI configuration files.
* `chore:` - When changes do not modify source or test files. E.g. Wpdating a dependency that does not require code changes.
* `docs:` - When making documentation only changes.
* `feat:` - When adding a new features. E.g. adding a new parameter to perform a new task.
* `fix:` - When making a bug fix.
* `refactor:` - When making code change that does not fix or add new features.
* `perf:` - When making code changes to improve performance.
* `revert:` - When reverting a previous commit.
* `style:` - When making formatting changes that does not affect the code. E.g. commas, semi-colons, whitespaces, indentioned, etc.
* `test:` - Adding missing or correcting existing tests.


### `Scope`

`Scope` can also be applied to the commit messages to provide more insight to where the changes are made. For example: if a change is being made only to the `android` source code, you can use `android` as the scope.

Example: "**feat(android): added support for abc**"

## Update with Upstream

Periodically your cloned repo's branch and PR may become out-of-dated with upstream's master. You should make sure your branch is up-to-date with the original repo:

```bash
git fetch upstream
git merge upstream/master
```

[Submit a pull request](https://help.github.com/articles/creating-a-pull-request/).
## After Submitting a PR

At this point you're waiting on us. We do our best to keep on top of all the pull requests. We may suggest some changes, improvements or alternatives.
Some things that will increase the chance that your pull request is accepted:
- Write tests.
- Write a [good commit message](http://chris.beams.io/posts/git-commit/).
- Make sure the PR merges cleanly with the latest master.
- Describe your feature/bugfix and why it's needed/important in the pull request description.

* Write tests
* Write a good commit message
* Make sure the PR merges cleanly with the latest master.
* Describe your feature/bugfix and why it's needed/important in the pull request description.
* Link your PR with the associated issue ticket is present

## Editor Config

The project uses [.editorconfig](http://editorconfig.org/) to define the coding
style of each file. We recommend that you install the Editor Config extension
for your preferred IDE. Consistency is key.
The project uses [.editorconfig](https://editorconfig.org/) to define the coding style of each file. We recommend that you install the Editor Config extension for your preferred IDE. Consistency is key.

## ESLint

The project uses [.eslint](http://eslint.org/) to define the JavaScript
coding conventions. Most editors now have a ESLint add-on to provide on-save
or on-edit linting.
The project uses [.eslint](https://eslint.org/) to define the JavaScript coding conventions. Most editors now have a ESLint add-on to provide on-save or on-edit linting.

We look forward to your contributions!
26 changes: 0 additions & 26 deletions .github/ISSUE_TEMPLATE.md
View file

This file was deleted.

39 changes: 39 additions & 0 deletions .github/ISSUE_TEMPLATE/BUG_REPORT.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
---
name: 🐛 Bug Report
about: If something isn't working as expected.

---

# Bug Report

## Expected Behaviour

## Actual Behaviour

## Reproduce Scenario (including but not limited to)

### Steps to Reproduce

### Platform and Version (eg. Android 5.0 or iOS 9.2.1)

### (Android) Device Vendor (e.g. Samsung, HTC, Sony...)

### `cordova info` Printout

<!--
Please attach the full `cordova info` print out.
This printoput contains all the necessary information for debugging.
The information it provides:
* Versions of the Cordova Packages
* Project Installed Platforms & Versions
* Project Installed Plugins & Versions
* Development Environment Information
* <Platform> Environment Information
* Project Setting Files (config.xml and package.json)
-->

### Sample Push Data Payload

### Sample Code that illustrates the problem

### Logs taken while reproducing problem
19 changes: 19 additions & 0 deletions .github/ISSUE_TEMPLATE/FEATURE_REQUEST.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
---
name: 🚀 Feature Request
about: A suggestion for a new functionality

---

# Feature Request

## Motivation Behind Feature

<!-- Why should this feature be implemented? What problem does it solve? -->

## Feature Description

<!-- Describe the feature in detail. Include if possible, code examples, screenshots, drawback, potential breaks. -->

## Alternatives or Workarounds

<!-- List alternatives or workarounds you are currently using to support this feature in your project. -->

0 comments on commit fe1cdf2

Please sign in to comment.