Re: OSL Docs


Larry Gritz
 

This is great, I'm thrilled to see you moving forward on these.

Note that we already have "contributing" and "install" documents in the current repo, and it's fine to just directly propose changes there. But if you are just intending osl-doc to be a staging area, someplace where you can temporarily start fresh without any distraction by or temptation to keep the existing docs, then that's fine, and when you feel they're ready, they can be moved back.

In the long run, any docs that are tightly coupled to a particular OSL version (API docs and installation docs, for example) probably belong in the main repo, as having them in a separate project just invites confusion or errors that result from somebody not having exactly the right corresponding versions of the two projects. The argument may be stronger for larger and not-tied-to-specific-versions documentation projects to be separate from the main code repo (the web site, or an extensive OSL shading tutorial might be good examples). These are all things where we can defer until farther down the road discussion of the merits of exactly where they should permanently live.

If you need a staging area, or eventually even a permanent second repository for things that should not be part of the main code repo, it is not necessary for you to do it in your own personal account. We can create secondary/scratch repos under AcademySoftwareFoundation, and there's no reason (especially for new material) to wait until we move the main repo from imageworks to ASWF (which will happen, hopefully, in the next few weeks anyway). Just give the word, and we can make you a new repo.

I also just gave you write permissions on the current repo (the imageworks one), so if you need to, you should feel free to make separate branches where you can work on in-tree docs (and even accept PRs into those branches only) without polluting master quite yet.

Any secondary repository should be populated with the OSL license files and notices (BSD 3-clause for code, Creative Commons CC BY 4.0 for docs) at the very least. You don't want to get to the point where you've collected contributions from a bunch of people, and then when it's time to re-integrate it into the main project, we can't do it because it's not legally clear what licenses it's covered by and you might need to track down every last person who contributed any bit and get their explicit ok to relicense it. Huge PITA.

-- lg


On Jan 8, 2021, at 1:50 PM, Mitch Prater <mprater@...> wrote:

Hi All,

I've created a temporary github project/repo for collecting any OSL documentation we're working on: https://github.com/mprater/osl-doc

I've never managed an on-line or collaborative documentation project before, so this is the best I could come up with. If there's a better way to go about this please let me know. I've initialized the repository with the work we've already done.

Please consider contributing useful information you may have.

Thanks, mitch

--
Larry Gritz




Join osl-dev@lists.aswf.io to automatically receive all group messages.