@vsoch this is good stuff. Do you think it makes sense in its own FAQ section at bottom? Regarding links etc., please see #188 where we are adding an appendix.

Also - can you fix the travis build?

0.06s$ TRAVIS_COMMIT_RANGE="${TRAVIS_COMMIT_RANGE/.../..}" make .gitvalidation
git-validation -q -run DCO,short-subject,dangling-whitespace
 b602e8f - FAIL - has whitespace errors. See `git show --check b602e8fce277faeb0b384f8de117f3090249f473`.
1 commits to fix
Makefile:54: recipe for target '.gitvalidation' failed
make: *** [.gitvalidation] Error 1

@jdolitsky @jonjohnsonjr that's a good idea to have them in FAQ - but is there a way we can link them back to where they are relevant? We'd want the person reading / implementing to read points when they are relevant, otherwise they might be missed entirely. Maybe a link from the FAQ back to the section, so for the section, a small list of relevant FAQ at the end of each?

okay I've moved all the question snippets into it's own FAQ section - it's not ideal in that it becomes unlinked from the relevant sections, but hopefully having it right before the specification sections (push, etc.) the user will at least glance over it and know to come back if there is a question.

I wonder whether this content should move to a separate "advice for implementors" or "implementation guide" document. That would accomplish a few goals:

1. Keep the spec document small and focused on requirements.
2. Allow the spec to link to sections of the implementation guide (or vice-versa), which would help with @vsoch's point about the two being unlinked.
3. Make it easy for the implementation guide to grow/evolve separately from the spec, which seems appropriate.

@adamwg I'm happy to do that, just let me know what you want. Also, it looks like there was a merge so now there is a merge conflict. I can attempt to resolve but I may not be familiar enough with what should be there to do it correctly.

okay looks like I was able to do it! Hopefully correctly, haha.

+1 to Adam's comment. This document could (and should) grow pretty large. Howabout an faq.md ?

That works as well. image-spec has something similar: https://github.com/opencontainers/image-spec

Moved.

@vsoch awesome. Can you fix the signoff error?

How exactly? I merged master into here from the interface, and here is the git history. Are you saying I have to start from scratch? Why is it so hard to contribute here? :(

Author: vsoch <[email protected]>
Date:   Thu Oct 8 09:30:35 2020 -0600

    moving questions to faq in readme
    
    Signed-off-by: vsoch <[email protected]>

commit c2077da8d4773ee2ac20562c49639b89f83e0833
Merge: 4f01bdd db37dc2
Author: Vanessasaurus <[email protected]>
Date:   Wed Oct 7 16:09:05 2020 -0600

    Merge branch 'master' into add/spec-details

I started from scratch and updated the files, I hope that worked. :/

@vsoch I understand the pain. Looks like it worked

@vsoch - apologies, but there was some conversation about this - can we move this into an faq.md in the root of the repo? There are a bunch more things we would like to add there

Sure thing! Let me pull and make the changes.

@vsoch - looks good, can you fix the sign-off issue? One of the commits must be missing it

All of the commits are signed (see verified in the Commits tab). What am I missing?

@vsoch - its the merge commit: c83bd62

I had to update from master (there was a merge conflict), I did that on GitHub automatically.