Feature/357 deploy to maven central

[davidjlynn]

This PR aims to give a method of publishing protoc-gen-doc to maven central. This aims to address issue #357.

Prerequisite

A maven central account is required, and this will have to be added to the repositories secrets, under these variables:

• OSSRH_USERNAME
• OSSRH_TOKEN

This guide can be used to apply for an account: https://central.sonatype.org/publish/publish-guide/#introduction I have previously done this for testing, and here is an example of the issue I opened: https://issues.sonatype.org/browse/OSSRH-50791

Implementation

I have used Gradle to publish to Maven, this allowed me to directly upload the artifacts which have been created in other build steps. I attempted to use Maven directly but Maven seemed to want to be more in charge of building and was not allowing the easy output of non-java libraries.

I have added some new steps to github actions which should publish the artifacts after they have been built.

Usage

With these changes, it should be possible to easily integrate this plugin in projects using google plugins, for example in the gradle plugin:

apply plugin: 'com.google.protobuf'

protobuf {
    protoc {
        artifact = 'com.google.protobuf:protoc:3.19.3'
    }

    plugins {
        doc {
            artifact = "com.github.pseudomuto:protoc-gen-doc:1.5.1"
        }
    }

    generateProtoTasks {
        all().each { task ->
            task.plugins {
                doc {
                    option 'html'
                    option 'index.html'
                }
            }
        }
    }
}

Notes

This has been very hard to test as this is folded largely into the release and build process. As such I am not fully confident with the changes. Perhaps we could do some extra testing before a new release. This is due particularly for the need for setup for the release process, and without access to the secrets it is hard to recreate this process in a fork.

[davidjlynn]

@pseudomuto I could you take a look at this proposal for Maven publishing? Thanks.

[MrBergin]

Fantastic to see a PR for this, been keeping an eye on that issue so I'm really grateful for this!

I think if you upload all artifacts with exe extension then consumers of the plugin can declare the GAV without classifier or extension, which makes it a little nicer to consume. For example if you take a look at the artifacts for grpc-java you can see they are all .exe, even for linux and osx.

In this case you could just set them all to exe as follows (I've assumed dist directory structure here, I've not tested it!):

            //linux 64 arm
            artifact("$projectDir/dist/protoc-gen-doc_linux_arm64/protoc-gen-doc") {
                classifier 'linux-aarch_64'
                extension 'exe'
            }
            //linux 64 intel
            artifact("$projectDir/dist/protoc-gen-doc_linux_amd64/protoc-gen-doc") {
                classifier 'linux-x86_64'
                extension 'exe'
            }
            //mac 64 arm
            artifact("$projectDir/dist/protoc-gen-doc_darwin_arm64/protoc-gen-doc") {
                classifier 'osx-aarch_64'
                extension 'exe'
            }
            //mac 64 intel
            artifact("$projectDir/dist/protoc-gen-doc_darwin_amd64/protoc-gen-doc") {
                classifier 'osx-x86_64'
                extension 'exe'
            }
            //windows 64 arm
            artifact("$projectDir/dist/protoc-gen-doc_windows_arm64/protoc-gen-doc.exe") {
                classifier 'windows-aarch_64'
                extension 'exe'
            }
            //windows 64 intel
            artifact("$projectDir/dist/protoc-gen-doc_windows_amd64/protoc-gen-doc.exe") {
                classifier 'windows-x86_64'
                extension 'exe'
            }

Then your downstream consumer would be able to declare the plugin like this:

protobuf {
    protoc {
        artifact = "com.google.protobuf:protoc:3.19.4"
    }
    plugins {
        doc {
            //no need for classifier / extension as gradle protoc plugin figures it out
            artifact = "com.github.pseudomuto:protoc-gen-doc:0.1.0"
        }
    }
    generateProtoTasks {
        all().each { task ->
            task.plugins {
                doc {
                    option 'markdown,grpc-docs.md'
                }
            }
        }
    }
}

Again thanks for this PR, I'm happy to lend a hand if needed.

[davidjlynn]

Thanks for the input @MrBergin, I have switched to use exe for all extensions for simplicity of use. This seems in line with https://github.com/google/protobuf-gradle-plugin#customizing-protobuf-compilation

I have also published the rest of the binaries, thanks for finding all the classifiers.

[pseudomuto]

I've opened the ticket with for the MC account here

[pseudomuto]

Ok, secrets have been added. Thanks so much for the PR! I'm going to get this merged. Then I'll try to release a snapshot build using gradle. If that works as expected, I'll cut a new proper release.

[davidjlynn]

@pseudomuto I was just looking through the issue you opened for the user, it looks like you have been put on a different sonatype cluster than I was (apparently due to number of users they have opened a new one). I will open a PR to switch to the new deploy URL, just in case it makes a difference.