mattbdean / Jraw

repositories {
    jcenter()
}
dependencies {
    implementation "net.dean.jraw:JRAW:$jrawVersion"
}

Documentation

The full documentation is available on GitBooks, but here's a sneak peek:

// Assuming we have a 'script' reddit app
Credentials oauthCreds = Credentials.script(username, password, clientId, clientSecret);

// Create a unique User-Agent for our bot
UserAgent userAgent = new UserAgent("bot", "my.cool.bot", "1.0.0", "myRedditUsername");

// Authenticate our client
RedditClient reddit = OAuthHelper.automatic(new OkHttpNetworkAdapter(userAgent), oauthCreds);

// Get info about the user
Account me = reddit.me().about();

Javadoc

JRAW uses JitPack to host its Javadoc.

https://jitpack.io/com/github/mattbdean/JRAW/VERSION/javadoc/index.html

VERSION can be a specific commit hash (like d6843bf), a tag (like v1.0.0), or the HEAD of a branch (like master-SNAPSHOT).

JitPack produces Javadoc only when necessary, so the first time someone accesses the Javadoc for a specific build it may take a little bit.

Android

JRAW doesn't target Android specifically, but there is an extension library that solves some quality of life issues. Also be sure to check out the example app that shows how to get users logged in.

Contributing

To get started you'll need to create two reddit OAuth2 apps, one script and one installed, and then create a subreddit.

To have this done automatically for you, run this command:

$ ./gradlew :meta:credentials --no-daemon --console plain

Your testing account should have at least 100 karma, otherwise you'll run into issues when trying to create a subreddit.

lib/src/test/resources/credentials.json:

{
    "script": {
        "username": "...",
        "password": "...",
        "clientId": "...",
        "clientSecret": "..."
    },
    "app": {
        "clientId": "...",
        "redirectUrl": "..."
    },
    "moderationSubreddit": "..."
}

Then you can go ahead and run the tests

$ ./gradlew test

Tests are written with Spek and assertions are done with Expekt.

In order to get the integration tests of the docs module to pass, you'll need gitbook-cli installed globally. You shouldn't have to worry about this, as most of the contributions are likely to be towards the core library and not its accessory modules.

Code Style

Kotlin code follows the official conventions provided by JetBrains (with a few exceptions).

A few hard and fast rules:

• UTF-8 everywhere
• 4 spaces for indentation
• 120 line length

Releasing

Define these variables in gradle.properties:

# Go to gitbook.com -> Account Settings -> Applications/Tokens to get an API key
gitbookUsername=<gitbook username>
gitbookPassword=<gitbook API key or password>

# Go to bintray.com -> Edit Profile -> API Key to get your account's API key
bintrayUser=<bintray username>
bintrayKey=<bintray API key>

# If this property doesn't match the target release, all release-related tasks
# will be disabled
authorizeRelease=<version to release>

Update the version in the root build.gradle and then run the :lib:release task to perform a release.

$ ./gradlew release --no-daemon --console plain

This task will:

1. Clean everything and run :lib's tests
2. Run :meta:update (see here for what this does)
3. Creates a commit for the version. This commit must be pushed manually later.
4. Updates the GitBook site and creates a new tag in the Git repo.
5. Uploads artifacts (sources, Javadoc, and compiled) to Bintray

After running the task:

1. Push the newly-created commit
2. Create a GitHub release targeting that commit. Attach all jars generated in lib/build/libs.
3. Publish the uploaded jars on Bintray