CONTRIBUTING and OPEN_SOURCE_PLAN (#3)

Signed-off-by: Larry Gritz <lg@larrygritz.com>

CONTRIBUTING.md

@@ -0,0 +1,145 @@
+<!-- Copyright (c) 2021 Sony Pictures Imageworks, et al. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- https://github.com/imageworks/spk -->
+
+# Contributing to SPK
+
+Code contributions to SPK are always welcome. That's a big part of why it's
+an open source project. Please review this document to get a briefing on our
+process.
+
+
+## Communications
+
+* **Email**:
+
+  [spk-dev](https://groups.google.com/g/spk-dev) is our email list. It is
+  currently invitation only, but will be opened fully after the project is
+  public.
+
+* **Bug reports / Issue tracking**:
+
+  Please use [GitHub Issues](https://github.com/imageworks/spk/issues).
+
+  Eventually, the spk, spfs, and spawn repos will all be merged into a single
+  respository. In the mean time, please use the spfs and spawn issues only
+  for items specific to the code in those repos, and for any general topics,
+  file issues in the spk repository so they will stick with what will
+  eventually be the one true project.
+
+
+
+## Licenses and copyright
+
+SPK/SPFS/spawn are distributed using the [Apache-2.0 license](LICENSE.txt).
+
+SPK/SPFS/spawn are Copyright (c) 2021 Sony Pictures Imageworks, et al.
+
+Please note that the "et al" encompasses all the other contributors. We do
+not require transfer of copyright -- technically speaking, submitters retain
+copyright to all the individual changes or additions they make to the code,
+and are merely licensing it to the other project users under the Apache 2.0
+license.  "Sony" is named because the code was seeded from an internal
+project and the repository still lives in the Imageworks GitHub account.
+When the project is ready to be spun off into an independent organization
+(such as ASWF), the copyright notices will all change to be more generic.
+
+## DCO Sign-off
+
+This project **does not** require a Contributor License Agreement (CLA)
+for submitters. However, we do require a sign-off with the [Developer's Certificate of Origin 1.1
+(DCO)](https://developercertificate.org/), which is the same mechanism that
+the [Linux®
+Kernel](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/submitting-patches.rst#n416)
+and many other communities use to manage code contributions. The DCO is
+considered one of the simplest tools for sign offs from contributors as the
+representations are meant to be easy to read and indicating signoff is done
+as a part of the commit message.
+
+Here is an example Signed-off-by line, which indicates that the submitter
+accepts the DCO:
+
+`Signed-off-by: John Doe <john.doe@example.com>`
+
+You can include this automatically when you commit a change to your local
+git repository using `git commit -s`. You might also want to leverage [this
+command line tool](https://github.com/coderanger/dco) for automatically
+adding the signoff message on commits.
+
+> Rationale for DCO-only: (a) The ASWF and Linux Foundation and their legal
+counsel believe that DCO provides enough protection to the project and its
+users, and point to the fact that many critical industry projects (such as
+the Linux kernel) find DCO sufficient. Out of all the open source
+organizations under the Linux Foundation umbrella, ASWF is nearly alone in
+using CLAs for most projects. Let's try the lighter weight approach this
+time. (b) The nature of this project involves an expectation that many
+individual contributors will submit "recipes" for building and packaging a
+wide range of projects with spk, each recipe being a very small contribution
+with no significant IP, and we wish to keep the contribution friction to an
+absolute minimum. In past projects we have learned that requiring
+contributors to get their employers' legal departments to evaluate and sign
+CLAs very often makes developers decide that it's not worth bothering to
+contribute at all (i.e., nobody wants to spend weeks fighting bureaucracy
+just to submit a 6 line packaging recipe). (c) This also is less overhead
+for Imageworks, which, if we use a full CLA, would be responsible for
+collecting and recording the CLA signatures and making sure that all
+contributors had them on file.
+
+
+# Pull Requests and Code Review
+
+The best way to submit changes is via GitHub Pull Request from your own
+private fork of the repository. GitHub has a [Pull Request
+Howto](https://help.github.com/articles/using-pull-requests/).
+
+All code must be formally reviewed before being merged into the official
+repository. The protocol is like this:
+
+1. Get a GitHub account, fork imageworks/spk (or spfs or spawn) to create your
+own repository on GitHub. During the time that we are keeping the imageworks
+repos private (prior to announced public release of the open source project), please ensure that your own fork is also private.
+
+2. Clone your repo to get a repository on your local machine, and you
+   probably want to add a remote to the imageworks repo as well. From the
+   command line, this probably looks like:
+
+   ```
+   $ git clone https://github.com/YOUR_GITHUB_USERID/spk.git
+   $ cd spk
+   $ git remote add imageworks https://github.com/imageworks/spk.git
+   $ git fetch --all
+   ```
+
+3. Edit, compile, and test your changes in a topic branch:
+
+   ```
+   $ git checkout -b mytopic master
+   $ ... do your edits ...
+   ```
+
+4. Push your changes to your fork (each unrelated pull request to a separate
+"topic branch", please).
+
+   ```
+   $ git add ...files you changed...
+   $ git commit -s -m "Your commit message"
+   $ git push origin mytopic
+   ```
+
+5. Make a "pull request" on GitHub for your patch.
+
+6. If your patch will induce a major compatibility break, or has a design
+component that deserves extended discussion or debate among the wider spk
+community, then it may be prudent to email spk-dev pointing everybody to
+the pull request URL and discussing any issues you think are important.
+
+7. The reviewer will look over the code and critique on the "comments" area,
+or discuss in email. Reviewers may ask for changes, explain problems they
+found, congratulate the author on a clever solution, etc. But until somebody
+clicks the "approve" button in the review section, the code should not be
+committed. Sometimes this takes a few rounds of give and take. Please don't
+take it hard if your first try is not accepted. It happens to all of us.
+
+8. After approval, one of the senior developers (with commit approval to the
+official main repository) will merge your fixes into the master branch.
+

OPEN_SOURCE_PLAN.md

@@ -0,0 +1,83 @@
+<!-- Copyright (c) 2021 Sony Pictures Imageworks, et al. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- https://github.com/imageworks/spk -->
+
+# Open Source Execution Plan for SPK et al.
+
+This is our working plan for how to turn this into a fully public,
+community-developed and widely used project.
+
+Contributors should propose edits to this, add milestones or tasks I have
+forgotten, and check off items as they are completed. We'll only keep this
+document alive as long as it is useful to us.
+
+## Before any sharing
+
+There are some housekeeping tasks to perform to the code base before anyone
+outside Imageworks can have access to it:
+
+- [x] Set up external (but private) repos, add internal developers.
+- [x] Set up email list, add internal developers.
+- [x] The code needs a LICENSE file attached, and copyright notices affixed
+  to all the code modules.
+- [ ] (IP - lg) README, CONTRIBUTING guide, basic procedures, etc. -- the set of
+  things expected for any open source project.
+- [ ] (IP - ryan) Some work to make it buildable and testable, so that the initial
+  co-developers will actually be able to kick the tires.
+- [ ] (IP - ryan) If possible, set up initial continuous integration so we know it
+  builds outside of our environment and can pass basic tests.
+- [ ] (IP - lg) Get **final** business clearance to open source.
+- [ ] Add external developers to mail list, GitHub repos.
+
+
+## Initial private share to work toward minimal viable product
+
+The code is not currently ready to let just anybody use it -- it lacks a
+simple way to build it outside our environment, needs documentation, comes
+with no build/packaging recipes, etc. We don't want to go "public" until
+it's in shape that it will make a good first impression and be useful for
+people to start using.
+
+We propose to host it on GitHub in the Imageworks area, but as private
+repositories that are only visible with per-user permissions. We will
+initially invite the other people who have expressed interest in helping us
+to co-develop the software moving forward. As we start to talk more publicly
+about what we're working on, we can also invite anyone else who subsequently
+expresses an interest in helping with the process.
+
+The purpose of this privately shared period is get to a "MVP" state, which
+involves at least the following:
+
+- [ ] Let the other presumed contributors see the code for the first time, try it out, evaluate it, figure out which parts need alteration to suit their needs, and which parts of the project moving forward they would like to help with.
+- [ ] Set up a regular stakeholder meeting cadence.
+- [ ] Combine the (currently) three repositories (for the file system layer, the packager, and the application launcher) into a single project/repository.
+- [ ] Make sure that it's easily buildable and deployable outside the SPI environment, including build/deploy documentation.
+- [ ] Set up a continuous integration system that can build and test the system, using GitHub Actions.
+- [ ] Figure out how to organize package recipes within the repository, and seed it with package recipes for all the common VFX packages so that it will be a useful working system "out of the box" when it goes truly public.
+- [ ] Set up web site and online documentation.
+- [ ] Need logo and other basic graphic design assets.
+- [ ] Achieve consensus on project governance -- who chairs meetings, how do we reach decisions, is there a chief architect with final call on technical disputes, how are people added to steering committee, etc.
+- [ ] Anything else, technical or organizational, that comes up or is identified by the co-developers, that we think needs to be fixed before it's ready to be public.
+
+
+## Public share
+
+When the stakeholders think that the project is ready to launch publicly, we can just switch the existing repository from "private" to "public." We'll probably want some announcement or PR at that time.
+
+
+## Possible ASWF future
+
+It certainly seems like an ideal project to turn over to the ASWF. It is hard to determine the best timeline for this at this point, particularly before the other co-developers have been fully identified and before any of them have had a chance to see the project in action.
+
+It may be that the right approach is to continue hosting it in the Imageworks GitHub account until it reaches a maturity level that the stakeholders decide they want to apply to turn it over to the ASWF. It is also possible that soon after the stakeholders see it and start working, they will desire to have it hosted in a truly neutral place like the ASWF as soon as possible, as a way to provide an even better foundation upon which many parties can collaborate. We will see how it goes and collectively decide when the time is right to try to have it hosted at ASWF.
+
+
+## Proposed Timeline
+
+This is all subject to change; this is just a stake in the ground to
+document a possible future.
+
+- Immediately: Set up private repos (without sharing with anyone outside), start working on the "pre-share" tasks listed above.
+- By the end of next week (Apr 23), if possible: invite the outside stakeholders to have read permissions on the private repository.
+- SIGGRAPH might be a good goal for a "go public" date and formal announcement about the project. The actual date for switching the repo to public visibility might be somewhat before or somewhat after, depending on how quickly we can accomplish the "private share" tasks.
+- TBD when the right time is to apply for ASWF governance of the project, we'll have to see how the other steps go.

README.md

@@ -1,3 +1,7 @@
+<!-- Copyright (c) 2021 Sony Pictures Imageworks, et al. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- https://github.com/imageworks/spk -->
+
 # SPK
 
 Package Manager for SPFS.
@@ -18,6 +22,32 @@ All Rights Reserved.
 SPK/SPFS/spawn are distributed using the [Apache-2.0 license](LICENSE.txt).
 
 
+## Structure of the spk project
+
+`spfs` is the per-process layered file system.
+
+`spk` is the software packaging system built on top of SPFS.
+
+`spawn` is the application launcher for spk packages.
+
+These are spread over three code bases at the moment, but will probably
+be merged into a single project, [spk](https://github.com/imageworks/spk).
+Please refer to [spk](https://github.com/imageworks/spk) for almost all
+information about staging the open source project, that's where the
+developer documentation and communication will live, including
+[Contributing to SPK](https://github.com/imageworks/spk/CONTRIBUTING.md).
+
+
+## Contributing
+
+Please read [Contributing to SPK](https://github.com/imageworks/spk/CONTRIBUTING.md).
+
+
+## Development plan
+
+Please read [SPK open source development plan](https://github.com/imageworks/spk/OPEN_SOURCE_PLAN.md).
+
+
 ## Development
 
 SPK is mostly written in python, with a Rust extension that integrates with the spfs API.