Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
It would be useful if there were a wiki that provided reference material associated with the various providers. It can be somewhat difficult to track down the documentation about endpoints, scopes, response bodies, etc.. This information has to be researched when creating a provider for the first time, so it couldn't hurt if it was recorded at that time. This should help in the long run in maintaining the code when the provider updates there service. Here is a sample associated with the Google provider:
Auth and Token Details:
I think it would still merit having a significant portion if it outside the code base. It is easier to diff code changes version to version if there is not a large portion of changing comments sprinkled throughout a file. Plus some of this type of information could be hard to find if it was dispersed throughout a code base. Regardless of whether it is put in the code or in a wiki, it will eventually get dated. If it was in the code would you then not want to accept a pull request if a volunteer submitted code fixes but didn't update the documentation.
To directly answer your question, I would not accept the PR as is. That's what is done on other Hapi repos.
Now, I would love to better document each provider from a user's perspective. I think that this is not documented currently (spread around the README.md and I am not sure if it is exhaustive). So document, exactly what type of options you can pass to it in a specific section of the README or its own markdown file.
Having a link to the specifics of each implementations, facebook docs, google docs, phabricator docs, ... I could see that being put with that documentation. But I would not summarize that information in here.
Would you be alright with such a solution or is there something I am missing?