Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

specification info page #662

Merged
merged 3 commits into from May 5, 2019

Conversation

@choldgraf
Copy link
Collaborator

choldgraf commented May 2, 2019

This is a fairly lightweight information page that coins the term "Reproducible Execution Environment Specification" (REES), and provides a little bit of explanation for what it is. In the future, we could flesh out this page a bit more.

closes #656

WDYT @betatim ?

docs/source/specification.rst Outdated Show resolved Hide resolved
docs/source/specification.rst Outdated Show resolved Hide resolved
@minrk
minrk approved these changes May 3, 2019
docs/source/specification.rst Outdated Show resolved Hide resolved
docs/source/specification.rst Outdated Show resolved Hide resolved
@choldgraf

This comment has been minimized.

Copy link
Collaborator Author

choldgraf commented May 3, 2019

Thanks all for the great comments + edits, what do folks think about the latest push?

Preview of the page: https://17-93201080-gh.circle-artifacts.com/0/html/specification.html

@choldgraf choldgraf force-pushed the choldgraf:rees branch from c0590fa to 8df1595 May 3, 2019
@choldgraf choldgraf force-pushed the choldgraf:rees branch from 8df1595 to 1c66925 May 3, 2019
@betatim

This comment has been minimized.

Copy link
Member

betatim commented May 3, 2019

Ready to merge or do you want to tweak/work on it some more?

@choldgraf

This comment has been minimized.

Copy link
Collaborator Author

choldgraf commented May 3, 2019

I'm fine merging as-is with the idea that we'll keep iterating on this moving forward. Understand if folks want to hold off though!

@choldgraf choldgraf referenced this pull request May 3, 2019
5 of 5 tasks complete

Any collection of files taken from the :ref:`config-files`
list, placed either in the root of a folder or in a sub-folder called
either ``binder/`` or ``.binder/``.

This comment has been minimized.

Copy link
@betatim

betatim May 3, 2019

Member

Could we turn L20-24 into something like "Any directory containing zero or more files from the config-files list is a valid reproducible execution environment as defined by the REES. The configuration files have to all be placed either in the root of the directory, in a binder/ sub-directory or a .binder/ sub-directory."?

In my mind a specification is a document that describes a thing which it defines. What I was expecting is something like "The HTTP spec defines that a HTTP request consists of a header and possibly a body. The header is separated from the body by two \n. A valid header consists of zero or more lines ... etc" https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html Something like this is what I think of when I think of REES.

This comment has been minimized.

Copy link
@choldgraf

choldgraf May 3, 2019

Author Collaborator

I think eventually we should have that kind of more specific language in there, I agree

docs/source/specification.rst Outdated Show resolved Hide resolved
docs/source/specification.rst Outdated Show resolved Hide resolved
docs/source/usage.rst Outdated Show resolved Hide resolved
@betatim

This comment has been minimized.

Copy link
Member

betatim commented May 3, 2019

I left several more comments which feel a bit language lawyer-y but then a specification is like a legal text so ... :-/

@choldgraf choldgraf force-pushed the choldgraf:rees branch from 1a3233f to f86a06d May 4, 2019
@betatim
betatim approved these changes May 4, 2019
Copy link
Member

betatim left a comment

LGTM. Restarted travis to see why the stencila things broke.

@betatim

This comment has been minimized.

Copy link
Member

betatim commented May 4, 2019

For a new PR/something to ponder when we extend this document: we focus on the fact that a human should be able to look at a directory that is REES compliant and be able to figure out what to do. THis is a key feature. How about when we describe a config file and what a REES compliant tool should do with it we also have a "For a human" section that says what a human would have to do to (roughly) achieve the same goal (I think often to achieve exactly the same goal we'd have to link to the (many) lines of code with corner cases etc in repo2docker). install-python; pip install -r requirement.txt is probably what a human should do when they find a requirements.txt. Even though what repo2docker exactly does is to add flags like --no-cache-dir and use conda, etc.

Having the "as a human" section would make it clear we are serious about that angle and instil confidence in the reader that this is actually possible (and not some kind of fantasy).

@choldgraf

This comment has been minimized.

Copy link
Collaborator Author

choldgraf commented May 4, 2019

@betatim that makes sense to me - I agree we should highlight the human aspect of the specification, along with the desire to co-opt other workflows rather than define new ones. Wanna throw that into a new issue assuming that this spec will be merged?

@betatim

This comment has been minimized.

Copy link
Member

betatim commented May 5, 2019

Pressing merge despite the CI failures. I think the docker cloud part failed because they were doing maintenance during most of Saturday.

@betatim betatim merged commit 56708c6 into jupyter:master May 5, 2019
2 of 5 checks passed
2 of 5 checks passed
codecov/patch CI failed.
Details
codecov/project CI failed.
Details
ci/dockercloud Your tests failed in Docker Cloud
Details
ci/circleci: build_docs Your tests passed on CircleCI!
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.