dj-stripe: missing docs

If you have a problem with this project’s maintainership I invite you to actually voice your specific concerns in a separate issue rather than offer snark in an unrelated one.

You’ve probably been largely ignored because you’ve consistently taking issues off-track and off-topic, just like you’re doing here in this issue about … documentation.

I’ll also remind you not to be dickish to unpaid volunteers working on essentially entirely commercial software made available for free. This goes for this project and any other open source project you benefit from.

On Sat, Mar 23, 2019, 23:21 Kelly Storm notifications@github.com wrote:

I’ve tried to approach documentation a few times now, but never pushed anything in, for two reasons:

1. Because Stripe’s API has changed so quickly, so much, the code here has pivoted just as aggressively, so getting to the use-case scenarios and code examples is hard to maintain alongside functional maintenance to ensure efficacy, correctness
2. If you issue a PR here, better hope the maintainers like you, otherwise you can kick rocks. I’ve tried to help these guys for a while now, and the general response has been “eh, shut up you wrong I right”

You’re better off forking and writing your own documentation. Also allows you to fix things and add to the code when you need to, instead of waiting around for your PR to at least be considered, which it likely won’t unless the maintainers decide to like you that day.

Not a personal slight, mind you - it’s their codebase, they can treat contributors however they so desire. No one’s paying them to do this, so we should all go kick rocks, but again, you’re better off finding others who have pushed in examples like I did above, and piecing together your own documentation.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/dj-stripe/dj-stripe/issues/864#issuecomment-475909704, or mute the thread https://github.com/notifications/unsubscribe-auth/AAOXktl-LJoz0gCH6aWdz4HXeQxQgib-ks5vZqjngaJpZM4bp1n6 .

@aaronn I’ll try and add a simple working example of customer + subscription creation using Stripe JS this weekend to close this issue.

I’ve tried to approach documentation a few times now, but never pushed anything in, for two reasons:

1. Because Stripe’s API has changed so quickly, so much, the code here has pivoted just as aggressively, so getting to the use-case scenarios and code examples is hard to maintain alongside functional maintenance to ensure efficacy, correctness
2. If you issue a PR here, better hope the maintainers like you, otherwise you can kick rocks. I’ve tried to help these guys for a while now, and the general response has been “eh, shut up you wrong I right”

You’re better off forking and writing your own documentation. Also allows you to fix things and add to the code when you need to, instead of waiting around for your PR to at least be considered, which it likely won’t unless the maintainers decide to like you that day.

Not a personal slight, mind you - it’s their codebase, they can treat contributors however they so desire. No one’s paying them to do this, so we should all go kick rocks, but again, you’re better off finding others who have pushed in examples like I did above, and piecing together your own documentation.

See what I mean

see #913, particularly the view: https://github.com/dj-stripe/dj-stripe/pull/913/files#diff-8e79ca913e72e919e117907146fd6901

I want to make clear that I’ve acknowledged the project’s deficiencies several times here on Github. This is by no means a defence of what state the documentation is in. I’m just asking that snark and statements such as “your PR won’t be considered” aren’t tolerated as long as I’m around.

If your stuff’s not getting looked at, bug me directly if you must, email me if you like (email’s on the profile and github commits), etc and I’ll try to jump in. I get how frustrating it is to have PRs sitting idle. But please keep in mind time is limited, and time&effort spent defending the current sole active committer on this project is time&effort not spent reviewing PRs.

But yes you’re right @blackboxoperations is clearly passionate and I don’t meant to turn anyone off from the project. But I want to stress to you @blackboxoperations directly that although I appreciate your passion, I would think it more likely for your commits, PRs and comments to get through if you keep those things clear, focused and they don’t trail off into paragraphs and paragraphs of text touching various subjects all at once. It makes it a lot less likely that someone with limited time will spend a bunch of it reviewing the pre-review.

Atomic commits. Atomic comments.

Alright, I see where the confusion comes in. Let’s rip order from chaos this fine morning, and build a reality with the points below in order to understand what stripe.Customer.metadata[‘djstripe_subscriber’] is all about, and why it’s important precisely.

1. Start fresh, new application, new Stripe account, new database, new everything. You have 0 users, 0 Stripe customers, 0 subscriptions.
2. You create a Product on Stripe
3. You create a Plan for that Product on Stripe, which essentially represents the subscription the application’s users will be able to purchase
4. Your application has a page where a person may purchase that Plan, which is the technical wording for, “where a person subscribes”

step 4 here is where your concern re: checkout comes into play, s.t. you will have to provide access to the Plans for whatever Products you have through Checkout, which is fine as long as the Plans were created after Stripe put Checkout into place. I haven’t had to do it myself, but I did stumble through this edge-case a while ago, in that legacy subscribers who were paying for a Plan for a Product created before all these changes were made to the API (before 2018, really, this is for people who have been using Stripe for years) need to be migrated over to a Plan for the very same Product - in some way.

If this is where you’re getting confused or hung up, here’s the solution to this particular problem: you’ll have to write a custom script that migrates these customers to a new Plan for that Product, one that has been created using a recent version of the API, because Stripe can’t provide you with some of the awesome new points of functionality (metered and tiered billing, being the obvious big ones) until you do so.

Your options here? Not so bad, they look like this:

a. phase out your current subscriptions such that when each one’s billing period ends the subscription expires and a new subscription is created for the new Plan you created that’s identical to the previous one, except comes with all the latest bells and whistles

b. hard delete and silently create subscriptions, per subscriber, that are anchored with a free trialing period to pad out the remainder of that subscription’s period.

c. attach that anchored free trialing period subscription defined above to the customer and set their current subscription to expire at period end

a takes time, b isn’t advised but gets the job done, c is hard to pull off but in my opinion is what you want to do if you need to migrate a huge customer base over to the new way of doing things without disrupting business operations and screwing a massive revenue stream up at the business level.

I know c works, because I recently had to do c, for hundreds of accounts, and it was very delicate and dangerous work, so I’ve no doubt you understand you can’t take it lightly, but if you’re looking for a “can it be done?” then here’s your yes, it can be done.

1. Someone subscribes, and in doing so, a user account is created in your application, but no such djstripe_subscriber metadata exists on their Stripe Customer page.

2. Bob, the new intern, deletes the database, gets fired. Thanks, Bob.

3. You go in, recreate the database, and as you try to regenerate that first account, realize that you’ll recreate the Stripe Customer - and that doesn’t make sense to you. This is where djstripe_subscriber metadata comes into play. 7.1. you initialize your customers, where you create the application account on your end, and dj-stripe attaches a djstripe_subscriber bit of info to the metadata of the Customer object, so you’ll see djstripe_subscriber=1 on the Stripe end of things now. 7.1.1. this is the ./manage.py djstripe_init_customers command 7.2. you then sync your customers, where now dj-stripe won’t create a second, redundant Customer, but instead, connect the Django user account to the existing Stripe Customer account, and then… 7.2.1. this is the ./manage.py djstripe_sync_customers command 7.3. all invoices and charges, etc., get sucked down from Stripe into the application. 7.3.1. this is also a part of the ./manage djstripe_sync_customers command, so points 7.2 and 7.3 are one and the same, to be clear.

I wrote the script in that gist I shared with you, because I don’t believe the current version of dj-stripe executes the workflow loosely defined in point 7 above precisely as I just defined it . In other words, the gist I shared with you is a variant of the currently defined setup process, that carefully avoids Customer duplication. It does so, by first pushing up metadata into the current Stripe Customer accounts, where before we execute /manage.py djstripe_init_customers, we be sure that all the Django user accounts have been logically connected to all the Stripe Customer accounts.

Maybe dj-stripe does this now, maybe it doesn’t, but back to my first point on why I think the maintainers are focused on the right things, but things like this require people like you and I to work out, take some punches, and report back in with data, options, results.

In doing so, we can do things like this: hey, @therefromhere, does dj-stripe do this now, and if not, want me to change the current commands so that it does? And that is a lot easier than getting the maintainers to drop weeks of time and ignore their current work just to satisfy what is essentially edge-cases on the opposite end of the spectrum <— thus why I believe we do this work so we can meet them in the middle at the end of the day.

So here we are.

---

I’ll stop here and see if we’re still talking about the same thing, or if the morning coffee has gotten the best of me and I’m wildly off point.