Improve repo documentation #312

joshcanhelp · 2019-01-07T19:45:18Z

This PR removes all extra documentation from the README in favor of the a new set of pages on the docs site and a CONTRIBUTING.md.

…tion to 5.1.0

joshcanhelp · 2019-01-07T19:45:38Z

CHANGELOG.md

@@ -104,16 +104,11 @@
 ## [5.1.0](https://github.com/auth0/auth0-PHP/tree/5.1.0) (2018-03-02)
 [Full Changelog](https://github.com/auth0/auth0-PHP/compare/5.0.6...5.1.0)

-[State validation](https://auth0.com/docs/protocols/oauth2/oauth-state) was added in 5.1.0 for improved security. By default, this uses session storage and will happen automatically if you are using a combination of `Auth0::login()` and any method which calls `Auth0::exchange()` in your callback.


Moved to the Troubleshooting section of the SDK docs

I'd keep a small mention of it. Normally when people find an error the first thing is go check what changed (on the changelog). You could link the troubleshooting section in here as well.

joshcanhelp · 2019-01-07T19:45:48Z

CHANGELOG.md

 **Closed issues**
 - Support for php-jwt 5 [\#210](https://github.com/auth0/auth0-PHP/issues/210)

 **Added**
+- Added XSRF State Storage / Validation [\#214](https://github.com/auth0/auth0-PHP/pull/214) ([cocojoe](https://github.com/cocojoe))


Missing the main PR here ... no label previously

damieng · 2019-01-31T17:27:04Z

CONTRIBUTING.md

+To run tests on the SDK, you'll need to create a `.env` file in the root of this package with the following entries:
+
+- `DOMAIN` - Auth0 domain for your test tenant
+- `APP_CLIENT_ID` - Client ID for a test Regular Web Application


X for a test Y is a bit confusing phrase. Maybe "A Client ID for a Regular Web Application within your test tenant" ?

damieng · 2019-01-31T17:29:46Z

README.md

-## Author
+- implement authentication with multiple identity providers, including social (e.g., Google, Facebook, Microsoft, LinkedIn, GitHub, Twitter, etc), or enterprise (e.g., Windows Azure AD, Google Apps, Active Directory, ADFS, SAML, etc.)
+- log in users with username/password databases, passwordless, or multi-factor authentication
+- link multiple user accounts together


Is this a marketing approved block of text from somewhere? Linking multiple user accounts together could be misconstrued I suspect without clarifying it's consolidation from multiple sign on providers?

We have a similar footer on every repo. Mostly copy/paste whenever a new repo is created. I don't know if this is also copy-paste.

Blurb comes from our template:

https://github.com/auth0/open-source-template/blob/master/README-sample.md#what-is-auth0

... which came from our content team.

lbalmaceda · 2019-01-31T17:23:25Z

CONTRIBUTING.md

+- `DOMAIN` - Auth0 domain for your test tenant
+- `APP_CLIENT_ID` - Client ID for a test Regular Web Application
+- `APP_CLIENT_SECRET` - Client Secret for a test Regular Web Application
+- `NIC_ID` - Client ID for a test Non-Interactive Client Application


A note in case of a future refactor. Since you're using the "CLIENT" word for other constants, might as well use it here and be more descriptive. In the end these are just names one should easily see and remember. e.g. NON_INTERACTIVE_CLIENT_ID

lbalmaceda · 2019-01-31T17:27:28Z

README.md


-```
+```bash


lbalmaceda · 2019-01-31T17:28:32Z

README.md

-    }
-}
-```
+The values above should not be hard-coded in a production application but will suffice for testing or local development. Please see our complete guide on the [main documentation page](https://auth0.com/docs/libraries/auth0-php#getting-started) for more information on how to store and use these values.


can we give the first sentence more relevance? e.g. bold or >

lbalmaceda · 2019-01-31T17:29:50Z

README.md

-To run tests on the SDK, you'll need to create a `.env` file in the root of this package with the following entries:
+- Use [Community](https://community.auth0.com/) for usage, questions, specific cases
+- Use [Issues](https://github.com/auth0/auth0-PHP/issues) here for code-level support
+- Paid customers can use [Support](https://support.auth0.com/) to submit a trouble ticket for production-affecting issues. 


I'd normally merge both "community" and "support" under https://support.auth0.com/ which will route them accordingly.

I think it's good to call them both out.

"Paid customers" sounds off. How about "Customers with a paid Auth0 subscription" ? Keeps it more in-line with the phrasing at https://auth0.com/docs/support

lbalmaceda · 2019-01-31T17:32:15Z

CHANGELOG.md

@@ -104,16 +104,11 @@
 ## [5.1.0](https://github.com/auth0/auth0-PHP/tree/5.1.0) (2018-03-02)
 [Full Changelog](https://github.com/auth0/auth0-PHP/compare/5.0.6...5.1.0)

-[State validation](https://auth0.com/docs/protocols/oauth2/oauth-state) was added in 5.1.0 for improved security. By default, this uses session storage and will happen automatically if you are using a combination of `Auth0::login()` and any method which calls `Auth0::exchange()` in your callback.


I'd keep a small mention of it. Normally when people find an error the first thing is go check what changed (on the changelog). You could link the troubleshooting section in here as well.

lbalmaceda · 2019-01-31T17:33:14Z

README.md


 ## License

-This project is licensed under the MIT license. See the [LICENSE](LICENSE.txt) file for more info.
+The Auth0-PHP SDK is licensed under MIT - [LICENSE](LICENSE)


this link won't work. Needs to be LICENSE.txt

lbalmaceda · 2019-01-31T20:38:19Z

CONTRIBUTING.md

+
+- `DOMAIN` - Auth0 domain for your test tenant
+- `APP_CLIENT_ID` - Client ID for a Regular Web Application within your test tenant
+- `APP_CLIENT_SECRET` - Client Secret for a Regular Web Application within your test tenan


Suggested change

- `APP_CLIENT_SECRET` - Client Secret for a Regular Web Application within your test tenan

- `APP_CLIENT_SECRET` - Client Secret for a Regular Web Application within your test tenant

lbalmaceda

LGTM

github-actions · 2022-08-23T23:05:07Z

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.

joshcanhelp added 4 commits January 3, 2019 16:45

Remove examples, create CONTRIBUTING, add TOC to readme

ca73e03

Final missing pieces in README; move troubleshooting to docs page

237b3d7

move state validation note to docs; added missing PR for state valida…

d0bf011

…tion to 5.1.0

Move all examples to docs site

c393308

joshcanhelp commented Jan 7, 2019

View reviewed changes

joshcanhelp mentioned this pull request Jan 7, 2019

Add Auth0-PHP to Libraries section auth0/docs#7118

Merged

Merge branch 'master' into improve-repo-documentation

dc66bfd

joshcanhelp changed the title ~~[WIP] Improve repo documentation~~ Improve repo documentation Jan 30, 2019

joshcanhelp added Ready to Review labels Jan 30, 2019

damieng reviewed Jan 31, 2019

View reviewed changes

lbalmaceda reviewed Jan 31, 2019

View reviewed changes

PR feedback

ecf94bd

lbalmaceda reviewed Jan 31, 2019

View reviewed changes

PR feedback

6aa2e08

lbalmaceda approved these changes Jan 31, 2019

View reviewed changes

damieng approved these changes Jan 31, 2019

View reviewed changes

joshcanhelp merged commit 79b2611 into master Jan 31, 2019

joshcanhelp deleted the improve-repo-documentation branch January 31, 2019 22:44

joshcanhelp removed the Ready to Review label Jan 31, 2019

joshcanhelp added this to the v5-Next-Minor milestone Feb 13, 2019

github-actions bot locked as resolved and limited conversation to collaborators Aug 23, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve repo documentation #312

Improve repo documentation #312

joshcanhelp commented Jan 7, 2019 •

edited

Loading

joshcanhelp Jan 7, 2019

lbalmaceda Jan 31, 2019

joshcanhelp Jan 7, 2019

damieng Jan 31, 2019

damieng Jan 31, 2019

lbalmaceda Jan 31, 2019

joshcanhelp Jan 31, 2019

lbalmaceda Jan 31, 2019

lbalmaceda Jan 31, 2019

lbalmaceda Jan 31, 2019

lbalmaceda Jan 31, 2019

joshcanhelp Jan 31, 2019

damieng Jan 31, 2019

lbalmaceda Jan 31, 2019

lbalmaceda Jan 31, 2019

lbalmaceda Jan 31, 2019

lbalmaceda left a comment

github-actions bot commented Aug 23, 2022

	- `APP_CLIENT_SECRET` - Client Secret for a Regular Web Application within your test tenan
	- `APP_CLIENT_SECRET` - Client Secret for a Regular Web Application within your test tenant


		```
		```bash

Improve repo documentation #312

Improve repo documentation #312

Conversation

joshcanhelp commented Jan 7, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lbalmaceda left a comment

Choose a reason for hiding this comment

github-actions bot commented Aug 23, 2022

joshcanhelp commented Jan 7, 2019 •

edited

Loading