Some docs / use-cases / migrating guides would be usefull

[andrii-kovalenko-ct]

Trying to switch from previous github-pages plugin. That one was lack of documentation and description, but looks like this one not much better ((

For instance, previous plugin task publishGhPages fails silently if there is an authentication problem (without any reporting to terminal, unless switching on gradle debug mode), or if remote branch gh-pages does not exist (i expected it will create remote branch automatically if not exist) - it is not explicitly noted in the README and was very hard to figure out the issue reason ;(

Now, in the new one - i'm migrating and don't know where to put credentials.username/password, which i used in github-pages.

Is it possible to make some documentation with describing all the plugin features and a full list of all available properties to set with short description?

For example, this plugin description looks much more user friendly:
https://github.com/TheBoegl/gradle-launch4j

This one https://github.com/FibreFoX/javafx-gradle-plugin is also good, also supplied with examples.

Thanks

[ajoberstar]

Hopefully this doesn't sound dismissive... but the readme has what you're asking for already. The readme covers:

• Tasks that were created and what they're for
• Configuration section with all available properties, a description, and default value (if any)
• How to apply the plugin

The credentials part isn't documented because it wasn't carried over from the old plugin. I had the impression most people were able to use the Grgit system properties for that configuration and the hardcoded properties wouldn't be needed. If that's not true, you could open an enhancement for that.

I'm not going to defend the previous plugin's documentation, but wanted to point out that the branch issue was a bug (which I believe is fixed) so it wouldn't have been documented. It wasn't supposed to work that way.

[ajoberstar]

If you have any more specific documentation suggestions, I'm certainly willing to improve them, I just wanted to make the current doc clear.

[andrii-kovalenko-ct]

Sorry, looks like I just brought some legacy feeling from the previous application.

I didn't expect that the example in the README is full and complete - it looked to simple.

Honestly, i don't know how to use Grgit for authenticating git repos. We use a Travis build, that's why we are doomed to use HTTPS protocol with token. In the previous version we do:

githubPages {
    repoUri = 'https://github.com/blah-blah/repo.git'

    credentials {
        // with GitHub token only HTTPS protocol should be used as a repo Uri
        username = System.getenv('GH_TOKEN')
        password = ''
    }
}

And set hidden GH_TOKEN environment variable. How could we achieve this in the new version?

Thanks and one more sorry for the first "angry" comment.

[ajoberstar]

No problem. A migration guide probably would be useful to help people map things over. I've struggled with how to document the Grgit auth, since there are a fair amount of options. Maybe some use case examples would help.

In your Travis command you could specify:

-Dorg.ajoberstar.grgit.auth.username=$GH_TOKEN