CONTRIBUTING.md 4.1 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11
# How to Contribute

We'd love to get patches from you! The core team at Twitter is very passionate about the direction of the product, and thus we are seeking fix contributions over external feature PRs.

If you have anything you'd like to contribute, we recommend discussing it with the core team before writing it.

## Workflow

The workflow that we support:

1.  Fork twitter-kit-android
D
Dalton Hubble 已提交
12
2.  Check out the `master` branch
13 14 15
3.  Make a feature branch
4.  Make your cool new feature or bugfix on your branch
5.  Write a test for your change
D
Dalton Hubble 已提交
16
6.  From your branch, make a pull request against `twitter/twitter-kit-android/master`
17
7.  Work with repo maintainers to get your change reviewed
D
Dalton Hubble 已提交
18 19
8.  Wait for your change to be merged internally by staff
9.  Delete your feature branch
20 21 22 23 24 25

## Testing

We've use the standard [Android Testing tools](http://developer.android.com/tools/testing/testing_android.html). Most classes are currently using AndroidTestCase, but will slowly be migrated to JUnit 4.

```
26
Running ./gradlew test connectedCheck will perform the needed tests
27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
```

## Styleguide

* We follow the android coding guidelines, followed by the java coding convention.

* checkstyle and lint will be used to help enforce code style.

### Android Style Guide
https://source.android.com/source/code-style.html

#### errata:

* the style guide is unclear on the naming of private static final fields, they should be SCREAMING_SNAKE_CASE

P
Pascal Borreli 已提交
42
* AOSP uses Hungarian notation, however this is discouraged in modern open source libraries and applications. Instance variables should be named with CamelCase and without prefixes.
43 44 45 46

### Java Style Guide
http://google-styleguide.googlecode.com/svn/trunk/javaguide.html (MikeFu suggestion)

P
Pascal Borreli 已提交
47
* Limit the use of horizontal alignment. While it may aid readability, it creates problems for future maintainers. More [here](http://google-styleguide.googlecode.com/svn/trunk/javaguide.html#s4.6.3-horizontal-alignment)
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96
* For testing purposes, we allow static imports, as well, as wildcard imports. This exclusion is added to our checkstyle config.

### Javadoc Style Guide
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

See style guide, in particular, when documenting methods:

* Use 3rd person (descriptive) not 2nd person (prescriptive).
* Method descriptions begin with a verb phrase.
* Add description beyond the API name.
* Avoid descriptions that say nothing beyond what you know from reading the method name.

### Groovy / Gradle Style Guide


### Git Commit Message Style Guide
http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

http://who-t.blogspot.de/2009/12/on-commit-messages.html

* Commit message should describe why the change is being made with a high level overview of significant changes made.

* The first line of commit message should be no more than 65 characters long. This should be a short summary of your commit. Wrap subsequent lines to 80 columns.

* Write commit message in the imperative: "Fix bug" and not "Fixed bug"
or "Fixes bug."  This convention matches up with commit messages generated
by commands like git merge and git revert.

## Code Review

The twitter-kit-android repository on GitHub is kept in sync with an internal repository at
Twitter. For the most part this process should be transparent to twitter-kit-android users,
but it does have some implications for how pull requests are merged into the
codebase.

When you submit a pull request on GitHub, it will be reviewed by the
twitter-kit-android community (both inside and outside of Twitter), and once the changes are
approved, your commits will be brought into the internal system for additional
testing. Once the changes are merged internally, they will be pushed back to
GitHub with the next release.

This process means that the pull request will not be merged in the usual way.
Instead a member of the twitter-kit-android team will post a message in the pull request
thread when your changes have made their way back to GitHub, and the pull
request will be closed. The changes
in the pull request will be collapsed into a single commit, but the authorship
metadata will be preserved.

Please let us know if you have any questions about this process!