Don't use a dev branch for docs about docs HOT 10 CLOSED

Thanks for starting this conversation @mddub. One point to add to the discussion and evaluation of this - many people look at master and get angry if it's wrong. If we kill dev, there's likely going to be even more things that are wrong in master. (In my experience, this has been one of the successes of using dev, because we can merge things in more quickly and have multiple people then work to improve what's broken but is better than being missing.) A simple fix for this could be improving the starter guide to the docs, so people don't expect perfection...or something else. Any thoughts on this aspect? Looking forward to the discussion on this topic.

from docs.

@danamlewis I think PR discussion is the right place for vetting non-trivial changes to the docs. Merge quickly and fix later is bound to result in inconsistencies.

And yeah, I completely agree about a caveat. If there's not already one, I would include a statement like:

OpenAPS is an open-source project created entirely by volunteers. As such, this documentation is a continuous work in progress maintained by the community. (That includes you!)

As you read this guide, you may come across passages which are confusing, inconsistent, or out of date. We encourage you to contribute early and often to improving these instructions. (If you're not familiar with GitHub, follow our walkthrough to familiarize yourself with contributing.)

from docs.

Yes, that looks good. With that kind of language addition, I would be OK to
change the process.

But I want to make sure @bewest and @scottleibrand specifically chime in
this and voice other considerations and/or get consensus that we are
changing processes.

On Monday, May 23, 2016, Mark Wilson [email protected] wrote:

@danamlewis https://github.com/danamlewis I think PR discussion is the
right place for vetting non-trivial changes to the docs. Merge quickly and
fix later is bound to result in inconsistencies.

And yeah, I completely agree about a caveat. If there's not already one, I
would include a statement like:

OpenAPS is an open-source project created entirely by volunteers. As such,
this documentation is a continuous work in progress maintained by the
community. (That includes you!)

As you read this guide, you may come across passages which are confusing,
inconsistent, or out of date. We encourage you to contribute early and
often to improving these instructions. (If you're not familiar with GitHub,
follow our walkthrough http://... to familiarize yourself with
contributing.)

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#189 (comment)

Dana Lewis | http://OpenAPS.org | http://DIYPS.org http://diyps.org |
@danamlewis http://www.twitter.com/danamlewis |
http://www.linkedin.com/in/danalewis
"Doing something for someone else is more important than anything you would
do for yourself."

from docs.

I like the idea of merging small changes directly to master. We could keep dev around for big stuff that is incomplete, but change the directions to have all small PRs go to master, and just retarget big stuff to dev as needed.

from docs.

It's up to you. :-) I'll concede the extra dev steps have resulted in some inconsistencies where I've had to fix conflicts here and there. If the new process is simpler for most things and can be executed more consistently than the current one, I'm all for it. People like me who love to burn through branches can use their own forks. :-)

from docs.

Mark,

I completely agree with you on this one. I'm not a huge contributor, yet. ;-). And I can't say having this changed before would have made me more of a contributor, but I think it will reduce some of the perceived madness. :-). No offense intended to all the git geniuses that are very familiar with the whole Github process but for n00bs it does seem like madness at times. :-D. I'm beginning to wrap my head around the whole thing a bit, but I'm not THERE, yet!

from docs.

So I think the path forward is to change the "first PR" and related documentation to have people PR things to master by default. I don't think we want to completely delete the dev branch, as it is useful for staging big changes (like the AMA documentation) for things that aren't deployed to master yet in oref0, as well as for testing things like ReadTheDocs image link fixes that need to be done on a branch that RTD builds, not just a random feature branch. But most commits can and probably should go straight to master, which will simplify things quite a bit. (We'll just need to merge master back to dev occasionally to keep it up to date.)

Any objections to that?

from docs.

Sounds good 👍

from docs.

👍

from docs.

👍

from docs.