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

add minifest-spec #5

Merged
merged 19 commits into from
Nov 15, 2016
Merged

Conversation

pipermerriam
Copy link
Member

Conversion of Tim's #2 into a pull request so we can discuss individual parts.

@pipermerriam
Copy link
Member Author

Don't merge this yet. The idea is to move discussion into this PR so that we can discuss specific parts of the proposed spec.

@pipermerriam
Copy link
Member Author

This is potentially a YAGNI but I'm thinking that there should be a manifest_version so that future improvements to the package manifest specification can be accounted for. Without this a client will need to accounting for all variations between versions of the spec in order to be compatible with all of them.

@mhhf
Copy link
Collaborator

mhhf commented Oct 8, 2016

+1 for manifest_version
We should thing about extendability from the beginning, since the space and its requirements are changing rapidly.


## Data to be stored within the manifest

- package name
Copy link
Collaborator

@mhhf mhhf Oct 8, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://gitter.im/ethpm/Lobby?at=57f56bf03c59573f6f0fd448

Tim Coulter @tcoulter Okt. 05 23:09
I’m contemplating we remove the name. That sounds like it might be registry level - lest the manifest name and the registered name not match.

I support this 👍

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I revoke my decision, a user given package name which doesn't depend on anything is a good thing. It can be seen as the most important made-up keyword.

- package name
- author
- version (preferably [semver](http://semver.org/))
- description
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should split this in a description (abstract), and a tags field.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

- deployed address if applicable
- name/address pairs for linked libraries
- compiler version for bytecode verification
- key/value pairs of the sha3 hash of events this contract can emit with the abi definition of that event (i.e., the contract metadata should contain information for all events that can be triggered by this contract, including those triggered by linked libraries)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be omitted - as it can be reconstructed out of the other infos.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 this is leftover from the previous version as I'm delaying on trying to define these parts.

@mhhf
Copy link
Collaborator

mhhf commented Oct 8, 2016

In dapple we found the need to store different environment information associated with a package/ deployed contract:
One simple use case could be a deployed Token contract stored together with its initial_balance which could look like this (admittedly very solidity centric):

...
"environment": {
  "token": {
    "type": "Token",
    "value": "0x67658a48be1b39db1c111dfca6f8fed09ac0da4e"
  },
  "initial_balance": {
    "type": "uint",
    "value": "0xffffff"
  }
}

should this be part of the manifest or solved on a different level?

@pipermerriam
Copy link
Member Author

I just pushed a pretty big update to this which attempts to define things a bit more precisely.

Copy link
Collaborator

@mhhf mhhf left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 Really like where this is going.
In generell I think we should be as close as possible to the metadata format provided by the foundation, once its finalized: https://pad.riseup.net/p/7x3G896a3NLA

TODO: define this

- contract metadata
- abi
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Highly suggest adding natspec into this list

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added

- unlinked binary
- deployed addresses
- linked libraries
- compiler version for bytecode verification
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • flags (e.g. optimized)

Copy link
Contributor

@tcoulter tcoulter Nov 2, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interesting suggestion. This spec is also assuming one specific contract language (solidity) and one specific compiler (solc). We might want to make compiler an object which contains information of the form:

{
  name: "solc",
  version: "0.4.2-342342342.a",
  flags: "--optimized" // or whatever it is
}

This would allow other solidity compilers to spring up, which is likely something to happen in the future. That said, probably a pre-optimization right now, and version 2 of the spec could implement it.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added

* Type: String


### Links: `links`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could this be solved on a higher level? Links are ephemeral, and I think we can do better.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably but I'm not exactly sure how. Adding a TODO note for this to be figured out.

- abi
- unlinked binary
- deployed addresses
- linked libraries
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • deployed addresses
  • linked libraries

I'm critical about this. I hope we can discuss it in detail.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Meta: I deleted a previous comment here because I need to put more thought into it.

* Package Manager Guide: Package Managers should validate this field conforms to the *semver* format and display a warning if it does not.


### Description: `description`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd suggest to add tags/keywords additionally to the description. Tags are the new links in the semantic web. Also every scientific paper provides keywords along the abstract.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aside: npm's package.json spec includes keywords as well, and is meant to help search. I wonder if that can help us with search as well.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a new keywords section for this.

* Type: String
* Package Manager Guide: Package managers should use this field when registering new packages (TODO: define this better)

### Author: `author`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Author(s). In case there are several.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 authors

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed to authors

* Key: `links`
* Type: Hash(String: String)

### Contract Meta: `??-TODO-??`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Contract(s)
In case this is not a typo, why do you think they shouldn't be several contracts per package?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed to be plural.

- external project URIs (homepage, repository uri, etc.)
- dependencies (i.e., references to other packages and versions)
- updated time (likely added by the packager)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where does the solidity source code live?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My guess is external project URIs, which could be links to IPFS hashes, but we could include some other construct.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mhhf I added a new stubbed out section for source code.


## Base Contract

These packages do provide any deployed instances of their contracts as they are
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be "do not provide"

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed

@tcoulter
Copy link
Contributor

tcoulter commented Nov 2, 2016

Awesome work Piper. Thanks for doing this.

observable block at the time of release.

* Key: `chain`
* Type: Hash(BlockNumber: BlockHash)
Copy link

@AFDudley AFDudley Nov 4, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems more reasonable:
https://github.com/bitcoin/bips/blob/master/bip-0122.mediawiki

Actually, instead of chain we need a URI to a "registry" which I still think should be called a repository because it will contain all the linked release-manifests, but I don't want to argue about language if everyone else as agreed to call these registries... I think both terms are a little overloaded.

Registry URIs make specifying dependencies easier.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In our call yesterday we discussed avoiding including anything registry related in this specification. We will still need to validate that is viable over the next few weeks but it's a nice simplification.

Another argument against including any registry information in these documents is it would make it more difficult to use a private mirror of packages which is a common use case for companies who don't want to have dependencies on 3rd parties for their build system. Being able to have registry data declared at the package manager level should allow this.

In order to be sure that we can still support verifiable builds, our plan is to ensure that both the source and dependency data can be verified by whatever link format we choose (such as including a checksum).

Does this satisfy your requirements?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I definitely agree with @AFDudley that we should implement something along the lines of the ChainID/URI scheme here...it is a very flexible approach and effective approach to working with multiple chains. I think the terms are being overly loaded here. I think the main point of contention is the ability to get EXACTLY what we are looking for in any chains context...which is all very doable with this. I think doing something along this line will enable solidity contracts to be ported over to areas like Rootstock (if for whatever reason they want to do that) or to permissioned chains, or to EVM forked projects.

Alternatively as was suggested in the meeting on Wednesday, we could utilize IPFS to make this happen as its hashing could point to a specific tx in a specific block in a specific chain.

populate the release manifest version field from the package
manifest version when creating a new release.
* Validation of the concept of Package Dependencies vs Release Dependencies
* When a dependency is defined at the package level it *can* be either pinned to a specific release, or possibly a range of releases such as `^0.4.0` to allow any version in the `0.4.x` line.
Copy link

@AFDudley AFDudley Nov 4, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How would a package manager resolve the range without first going to the repository on-chain? and why would the repository on-chain contain anything but the most recent version? Is this because the blockchain is just monotonically increasing packages?

npm pinning was/is broken for a long time, we should discuss via an issue or on gitter how version resolution would actually work.

I think the only thing that makes sense is release dependencies are {repo_URI}/package_name (this can also be a content hash). Package dependencies can specify {repo_URI}/package_name:semver. If that exact version isn't in the repository, the "package" manager will do a repository rebuild (whatever that means). The reason this is so different from all other package managers is because everything in the release manifest must be statically linked.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see dependency resolution occurring as follows when the package manager encounters a dependency such as string_lib: ^0.4.0.

  • Package manager uses whatever registrar(s) it is configured to use to resolve all relevant version numbers that match the given semver. (if the value isn't a valid semver it probably just looks for an exact string match).
  • Package manager picks the greatest version that matches the specified semver number for the dependency.

You say "why would the repository on-chain contain anything but the most recent version?". I'm not sure I follow your logic at all here because my experience with package indexes is that they keep references to every release that's ever been made. I'm not sure why this would be any different.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Package manager uses whatever registrar(s) it is configured to use to resolve all relevant version numbers that match the given semver. (if the value isn't a valid semver it probably just looks for an exact string match).

The problem with this is you're not conflating two different packages. The same package name and version from two different repos is not the same package.

Package manager picks the greatest version that matches the specified semver number for the dependency.

Although semver helps with this, you're exploding the complexity of verifying the contract graph with this decision. It's better to keep the graph being verified small by defining its nodes as explicitly as possible. We are concerned with validating DAGs of contracts, right?

I'm not sure I follow your logic at all here because my experience with package indexes is that they keep references to every release that's ever been made. I'm not sure why this would be any different.

For example, FreeBSD does a "ports freeze" before release to insure that the ports tree used for the production release is stable. (https://www.freebsd.org/doc/en_US.ISO8859-1/articles/committers-guide/ports.html#ports-qa-freeze-what)
Given that one of the major goals of this process is to verify that a package will perform as advertised in an adversarial environment, we need to support the ability to provide verified (and versioned) repos. I think we discussed this on gitter or something?

Copy link
Member Author

@pipermerriam pipermerriam Nov 13, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Semver vs Allowing any version numbering scheme.

I understand that allowing non-semver version numbering adds complexity to package manager implementations but I'm still not comfortable requiring semver since I know of plenty of major software packages that use alternate versioning schemes.

Free BSD Thing

I understand what you are talking about with your FreeBSD example. I just don't understand at all how it applies to this specification.

Pinning Dependencies.

I understand that two packages with the same version and name on two different package indexes can be different packages. The current specification allows for un-ambiguously pointing at a specific release via an IPFS URI.

Would it your stance on this if the spec was modified such that in the cases that a dependency was declared as a package_name/version pair that we supported some sort of content-hash as well so that once the dependency has beel resolved a package manager can then verify that the resolved package is the expected package?

Something like (psuedo-code, real spec would use something like multihash):

  'build_dependencies': {
    'string-lib==1.0.0#d41d8cd98f00b204e9800998ecf8427e'
  }

Copy link

@AFDudley AFDudley Nov 14, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I understand that allowing non-semver version numbering adds complexity to package manager implementations but I'm still not comfortable requiring semver since I know of plenty of major software packages that use alternate versioning schemes.

I actually don't care if it's semver or not. The issue is your proposal allows for two different packages to resolve to the same identifier for no practical reason.

I guess this is actually the root of all of my confusion, why are you arguing so hard for not having global addressing of packages in this file? we have been discussing adding two fields that change Big-O dependency resolution from (n * semver)^(n * semver) to c. it's such an insanely easy optimization I don't understand what you don't understand about it.

I understand what you are talking about with your FreeBSD example. I just don't understand at all how it applies to this specification.

Again, just trying to get global package identifiers See the big-O discussion above.

The current specification allows for un-ambiguously pointing at a specific release via an IPFS URI.

I think a blockchain URI makes more sense than an IPFS one. I think relying on IPFS in the spec is kinda lazy, We should make the content-addressing hash pluggable.

Would it your stance on this if the spec was modified such that in the cases that a dependency was declared as a package_name/version pair that we supported some sort of content-hash as well so that once the dependency has beel resolved a package manager can then verify that the resolved package is the expected package?

I think a BIP122 URI is better than a protocol-dependent content-hash but a protocol independent content-hash is at least as good as a BIP122 URI if not significantly better. I understand Swarm has adopted IPFS' content-hashing so if the spec is:

<package_name>==<semver>#<pluggable_content_hash>

this makes sense to me. But mixing hashes and URIs seems sort of silly. either map the global URIs to the content-hashes or just use content-hashes. I think we should just refer to all external objects via URIs. or things that are trivial to convert to URI, content-hashes have this property, but they aren't human readable, I think putting the mapping from human readable to content-hash in this file is kinda weird... but I'd need to think about it more to be sure.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The thing is, apparently, we can create a blockchain URI with IPFS. Now granted, perhaps this is relying too much on IPFS, but it's a fairly solid protocol. There may also be room for a combination approach...But I'm not sure how we want to go about this...As for Swarm + IPFS, there is a difference in the headers, but I believe that could be added accordingly if they are there, we just need a way to get that one hash and then have the headers added subsequently.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, the above is a bit confused. My over-arching goal is to make it easy to say "These packages have been verified and tested together". Part of achieving that goal is mapping the name of a package to the source and byte code of a package, such that there is no ambiguity to the people reading it. Content-addressing half helps, because I can't assume that IPFS will be available just because a customer is using the EVM. Also, traditional URIs and content-addressed URIs are both URIs so any place where we are specifying a content-address we could more generally specify a URI.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Either way, we should be able to map to both traditional centralized servers as well as DHTs.

@pipermerriam
Copy link
Member Author

+1

On Fri, Nov 4, 2016, 10:26 PM RJ notifications@github.com wrote:

@VoR0220 commented on this pull request.

In release-manifest-spec.md #5:

+this release.
+
+* Key: sources
+* Type: List of Strings
+
+
+### Chain: chain
+
+The chain field declares the blockchain that the contract addresses apply to.
+The chain is defined by a hash with block numbers as keys and block hashes as
+values. Both block numbers and hashes must be hexidecimal encoded.
+Convention is to include the genesis block under the key 0x00 and the latest
+observable block at the time of release.
+
+* Key: chain
+* Type: Hash(BlockNumber: BlockHash)

I definitely agree with @AFDudley https://github.com/AFDudley that we
should implement something along the lines of the ChainID/URI scheme
here...it is a very flexible approach and effective approach to working
with multiple chains. I think the terms are being overly loaded here. I
think the main point of contention is the ability to get EXACTLY what we
are looking for in any chains context...which is all very doable with this.
I think doing something along this line will enable solidity contracts to
be ported over to areas like Rootstock (if for whatever reason they want to
do that) or to permissioned chains, or to EVM forked projects.

Alternatively as was suggested in the meeting on Wednesday, we could
utilize IPFS to make this happen as its hashing could point to a specific
tx in a specific block in a specific chain.


You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
#5, or mute the thread
https://github.com/notifications/unsubscribe-auth/AAyTgmQ_RdMOhKpk4yxURcka8G_qqCuAks5q7AVygaJpZM4KN-4o
.

following keys for the following common resources.

* `website`: Primary website for the package.
* `documentation`: Package Documentation
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not necessary don't think. This should be done by the documentation generated from solidity code.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@VoR0220 this would be something like https://web3py.readthedocs.io/en/latest/. A URI to a website or other resource that represents the formal documentation for the package.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mmmm....yea I'm not sure this be included in the package manager, but its in the area that is up to interpretation so I'm okay with leaving it here so long as that is explicitly stated.


Package managers which are installing dependencies for development versions
should keep their own version of this document under the lowercased name of the
package manager such as `truffle.lock` or `dapple.lock`. This file would
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

++


* Key: `manifest_version`
* Type: Integer
* Allowed Values: `1`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SemVer this.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Never mind you already said this.

* Required: No
* Type: String
* Format: Hex encoded unlinked bytecode for the compiled contract.
* `runtime_bytecode`:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the difference between runtime_bytecode and normal bytecode? I also strongly believe that at the very least the ABI needs to be required. Quite possibly the bytecode too but not sure about that.

Copy link
Member Author

@pipermerriam pipermerriam Nov 11, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the difference between runtime_bytecode and normal bytecode?

My understanding is that bytecode is the code that can be used to deploy the contract. runtime_bytecode is the unlinked version of the code that you should expect to find at the address of a deployed instance of this contract (ie, what is returned by eth_getCode.)

I also strongly believe that at the very least the ABI needs to be required.

What about packages that don't provide any deployed contracts, but only contracts meant to be inherited from? Inclusion of ABI seems un-necessary in many of these cases.

Copy link
Contributor

@tcoulter tcoulter Nov 11, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

runtime_bytecode is the unlinked version of the code that you should expect to find at the address of a deployed instance of this contract (ie, what is returned by eth_getCode.)

eth_getCode doesn't return unlinked bytecode. Instead, it returns code that does not include a preamble; that is to say when you add a contract onto the network, the bytecode you're sending includes code that tells the vm to store your contract's code somewhere (i.e., create a new contract). eth_getCode only returns what was stored at an address by that preamble. (Aside: the preamble is standard, so you can add the binary for the preamble to anything returned by eth_getCode to get the code that was actually sent to the network.)

Regardless, I think it's important we include the unlinked bytecode which includes things like __SomeContract___________________ inside the bytecode to ensure we can relink packages as we see fit. (Although I suppose we could always recompile...)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think what you're trying to achieve with runtime_bytecode is be able to verify that the state is as it should be at a certain time, correct @pipermerriam ? If so I think that's incredibly valuable and the description should be updated to note this difference. It should be stressed that this is meant for safety and is not recommended for beginners use.

Copy link

@nmushegian nmushegian Nov 13, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Regardless, I think it's important we include the unlinked bytecode which includes things like SomeContract_________________ inside the bytecode to ensure we can relink packages as we see fit. (Although I suppose we could always recompile...)

@tcoulter yes!! this is mostly how dapple linking already works, originally we hoped to totally avoid addresses in contract constructors with this. Too bad solidity team only enabled this first-class for libraries which is a rather arbitrary distinction from a consumer's POV

Type: String
Format: TODO
* `settings`: TODO
* `link_dependencies`:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This may not need to exist as we might be able to find all of this from the metadata of a contract in future versions.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you expand on this? I don't understand.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Basically the metadata output from a contracts bytecode will compile to a json output that contains all linked dependencies and remappings and such to them.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah wait...if this is for linking in terms of Libraries, then yes this may in fact need to happen.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, this is meant to be used for library linking.

## Document Specification

The following fields are defined for the package manifest. Custom fields may
be included. Custom fields **should** be prefixed with `x-` to prevent name
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

must?

It is probably worth explaining the process of adding fields to the specification.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is another area where I don't want to be extra strict. If people want to use other keys I don't see why the spec should stand in their way.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is probably worth explaining the process of adding fields to the specification.

I don't think we actually have a process yet...

### Version: `version`

The `version` field declares the current version number of this package. This value
**should** be conform to the [semver](http://semver.org/) version numbering
Copy link

@axic axic Nov 11, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would argue it must conform to semver.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If people want to use whole number versioning I don't want to stop them. I agree that it's good for people to use this standard but there are lots of legitimate projects that don't use semver and I'm hesitant to put this as a requirement.

@axic
Copy link

axic commented Nov 11, 2016

Is it worth adding a license field (SPDX) to the manifest?


## Format

The canoonical format for the package manifest is a JSON document containing a
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

-> canonical

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Def: Canoonical: A humorous action performed in a canoe at or right around 12 Noon.


[![Join the chat at https://gitter.im/ethpm/Lobby](https://badges.gitter.im/ethpm/Lobby.svg)](https://gitter.im/ethpm/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

# Goals
Ethereum Packaging Specification
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Recommend we change this to EVM Packaging Specification as it relates to more chains than just Ethereum.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A bit more verbose but it could also be "Ethereum Smart Contract Packaging Specification" which may have more meaning to more people and still convey the same intent. Or "EVM Smart Contract Packaging Specification"

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I want to stress that this is for more than Ethereum. It is for the EVM. We can go with either or after the change from Ethereum to EVM is made.

Copy link
Collaborator

@mhhf mhhf Nov 12, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

EVM Smart Contract Packaging Specification

👍
Since indeed the use of packages could be used by different EVM chains like Rootstock

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.


A string matching the regular expression `[a-zA-Z][-_a-zA-Z0-9]*`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Still would like to recommend that we add a Group ID or Repository field into this.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For metadata purposes with have authors. For resolving packages I continue to push for keeping this out of the spec and leaving that up to package indexes.

Can you explain the use case for this again and why you think it belongs in these documents?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interoperability...ah wait yes, we did have this argument about this and decided that this would be able to work under ENS, correct?

@pipermerriam
Copy link
Member Author

added license field. Fixed canoonical.


* All keys **must** be valid package names matching the regular expression `[a-zA-Z][-a-zA-Z0-9_]*`
* All values **must** conform to *one of* the following formats:
* IPFS URI:

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like this could reference a file that maps to a different chain? This should only specify names.

@tcoulter
Copy link
Contributor

Any chance we can merge this and talk about minor changes as needed? A lot of what's in discussion right now can be easily changed.

@tcoulter
Copy link
Contributor

That is to say I'd prefer each one of these comments to be its own discussion.

@tcoulter tcoulter merged commit 6e42759 into ethpm:master Nov 15, 2016
@tcoulter
Copy link
Contributor

Merged. Hopefully I didn't derail discussions currently in progress. Please bring up new discussions as individual issues. Thanks guys!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants