Request for feedback: What's in a manifest file?

[Matt Farina]

Manifest files have become part of the conversation on package management. To grab and share some of the information on them I've started a document. I look forward to the feedback.

[Eric Johnson]

Some items to consider / add, that I noticed, upon comparison with Maven.

https://maven.apache.org/pom.html#More_Project_Information

The format of the manifest file (for future proofing)

Organization

Contributors

Bug trackers

CI tools

Mailing lists

Official source code location

Eric.

On 8/10/16 9:52 AM, Matt Farina wrote:
> Manifest files have become part of the conversation on package
> management. To grab and share some of the information on them I've
> started a document

> <https://docs.google.com/document/d/19_KtR0TxSOFCKCI_0jZAAmaqXueIRgxvTEmztuGl4_g/edit?usp=sharing>.

> I look forward to the feedback.

> --
> You received this message because you are subscribed to the Google
> Groups "Go Package Management" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to go-package-manag...@googlegroups.com
> <mailto:go-package-manag...@googlegroups.com>.
> To post to this group, send email to
> go-package...@googlegroups.com
> <mailto:go-package...@googlegroups.com>.
> For more options, visit https://groups.google.com/d/optout.

[Matt Farina]

Eric, I attempted to fill in the areas using Java. If someone sees I did something in error please note it.

On Wednesday, August 10, 2016 at 1:04:50 PM UTC-4, Eric Johnson wrote:

Some items to consider / add, that I noticed, upon comparison with Maven.

https://maven.apache.org/pom.html#More_Project_Information

The format of the manifest file (for future proofing)

Organization

Contributors

Bug trackers

CI tools

Mailing lists

Official source code location

Eric.


On 8/10/16 9:52 AM, Matt Farina wrote:
> Manifest files have become part of the conversation on package
> management. To grab and share some of the information on them I've
> started a document
> <https://docs.google.com/document/d/19_KtR0TxSOFCKCI_0jZAAmaqXueIRgxvTEmztuGl4_g/edit?usp=sharing>.
> I look forward to the feedback.
> --
> You received this message because you are subscribed to the Google
> Groups "Go Package Management" group.
> To unsubscribe from this group and stop receiving emails from it, send

> an email to go-package-management+unsub...@googlegroups.com
> <mailto:go-package-management+unsub...@googlegroups.com>.

[mhhcbon]

lgtm, thanks again putting it down.

I m please to see there is not too much fields.
I remember some hard time with debian packages,
there was too many fields to work with at beginning.

I d suggest to add the notion of require vs optional.

I did not clearly understand why those two last Prghs exist.

I d constrain the name to have a namespace, whatever it is (the user name, the organization),
because naming things is hard and when its about shared resources, there will be conflicts.
More stupidly, i can t think of a named resource (phone, mail, dns, address)
which does not have a namespace system in a way or another.
(On the other hand I feel the current way to require a package is perfect,
ie: github.com/some/what <> source/org/package, but yet this is more than the name, strictly speaking)

Will License field require a valid SPDX license value ?
I believe it should not be.
If in the past, license had been controlled by some central organization,
it is possible that wTF / cc / gpl / lgpl ect licenses would not exist today.
I believe the capability to create licenses, is a step forward to freedom.


Rather than Authors field, i d use Maintainer.
The one to enter in contact with for
human communication about a package.
Author is somehow confusing with the contributors,
and is not very expressive about the purpose of the field, imho.

I d add a dev-dep field.
For the test packages required to validate the package.

Have you considered a script section ?
NPM has this section to register small bash scripts in a formalized way.
So the later you can invoke the pm client in such fashion.

Few examples of the most well-known,

npm start: call the start script defined by the author to start the app
npm test: invoke the test suite (useful when there is multiple frameworks to test your code)
npm build: invoke the build script to generate some form of tarball (useful when Makefile is not the unique way to build)
npm publish: which command to run to generate a new version of the package and make it online

I like those 4 really much, i think they really are helpful.

[Matt Farina]

On Thursday, August 11, 2016 at 8:50:41 AM UTC-4, mhhcbon wrote:

lgtm, thanks again putting it down.

I m please to see there is not too much fields.
I remember some hard time with debian packages,
there was too many fields to work with at beginning.

Some manifest files have a lot of fields. pom.xml for Maven is a good example. I tried to keep the listing to common fields. If there are more people think would be useful to add please do so.

 

I d suggest to add the notion of require vs optional.

How would an optional dependency work for Go?

 

I did not clearly understand why those two last Prghs exist.

I d constrain the name to have a namespace, whatever it is (the user name, the organization),
because naming things is hard and when its about shared resources, there will be conflicts.
More stupidly, i can t think of a named resource (phone, mail, dns, address)
which does not have a namespace system in a way or another.
(On the other hand I feel the current way to require a package is perfect,
ie: github.com/some/what <> source/org/package, but yet this is more than the name, strictly speaking)

In the document I tried not to get too opinionated on what Go should do. I would expect Go to continue to use the name spacing it does today. I have not seen anyone suggesting that be changed.

 

Will License field require a valid SPDX license value ?
I believe it should not be.
If in the past, license had been controlled by some central organization,
it is possible that wTF / cc / gpl / lgpl ect licenses would not exist today.
I believe the capability to create licenses, is a step forward to freedom.


Rather than Authors field, i d use Maintainer.
The one to enter in contact with for
human communication about a package.
Author is somehow confusing with the contributors,
and is not very expressive about the purpose of the field, imho.

In the glide.yaml file I choose owners. It could be people or an organization. It's the responsible party.

Many places use the author signifier. That may be too individual person centric. It's worth discussing if we need such a field.

 

I d add a dev-dep field.
For the test packages required to validate the package.

I would consider this part of the dependencies section that I didn't go into too much detail on. There are a few different ways that could be handled.

 

Have you considered a script section ?
NPM has this section to register small bash scripts in a formalized way.
So the later you can invoke the pm client in such fashion.

Few examples of the most well-known,

npm start: call the start script defined by the author to start the app
npm test: invoke the test suite (useful when there is multiple frameworks to test your code)
npm build: invoke the build script to generate some form of tarball (useful when Makefile is not the unique way to build)
npm publish: which command to run to generate a new version of the package and make it online

I like those 4 really much, i think they really are helpful.

Is a scripts section common or more of an NPM thing?

[Humberto S. N. dos Anjos]

On Thu, Aug 11, 2016 at 5:21 PM, Matt Farina <matt....@gmail.com> wrote:

On Thursday, August 11, 2016 at 8:50:41 AM UTC-4, mhhcbon wrote:

Will License field require a valid SPDX license value ?

I believe it should not be.
If in the past, license had been controlled by some central organization,
it is possible that wTF / cc / gpl / lgpl ect licenses would not exist today.
I believe the capability to create licenses, is a step forward to freedom.

The document doesn't mention nor propose any requirements for a License field, but +1, just in case :)

 

Rather than Authors field, i d use Maintainer.
The one to enter in contact with for
human communication about a package.
Author is somehow confusing with the contributors,
and is not very expressive about the purpose of the field, imho.

In the glide.yaml file I choose owners. It could be people or an organization. It's the responsible party.

Many places use the author signifier. That may be too individual person centric. It's worth discussing if we need such a field.

I see this as a larger discussion for what situations a Go manifest file should cover. Maven handles three for Java: package management, project metadata and builds. A build tool for Go hasn't really been discussed, AFAIK (gb counts?), so basically the question is if a Go manifest file should handle project metadata as well. I don't think it should (that information is handled elsewhere, so the manifest ends up holding obsolete/malformed/incomplete data, therefore why bother), but that is a discussion for another time.

 

Have you considered a script section ?
NPM has this section to register small bash scripts in a formalized way.
So the later you can invoke the pm client in such fashion.

Few examples of the most well-known,

npm start: call the start script defined by the author to start the app
npm test: invoke the test suite (useful when there is multiple frameworks to test your code)
npm build: invoke the build script to generate some form of tarball (useful when Makefile is not the unique way to build)
npm publish: which command to run to generate a new version of the package and make it online

I like those 4 really much, i think they really are helpful.

Is a scripts section common or more of an NPM thing?

I feel that is the job of a build tool, which isn't being proposed.

[mhhcbon]

> How would an optional dependency work for Go?

My mistake, i mean, which field is required Vs which field is optional prior to a publish / require operation.
License may be optional, name is obviously required.

 

Have you considered a script section ?
NPM has this section to register small bash scripts in a formalized way.
So the later you can invoke the pm client in such fashion.

Few examples of the most well-known,

npm start: call the start script defined by the author to start the app
npm test: invoke the test suite (useful when there is multiple frameworks to test your code)
npm build: invoke the build script to generate some form of tarball (useful when Makefile is not the unique way to build)
npm publish: which command to run to generate a new version of the package and make it online

I like those 4 really much, i think they really are helpful.

Is a scripts section common or more of an NPM thing?

totally npmish.

 > I feel that is the job of a build tool, which isn't being proposed.

Understand your point.

It answers those question of an end user,
    How do i run/test/build/publish this package ?

That is where the two notions are mixed up, in those questions.

Yet i re assert there job is not to run/test/build/publish,
they only normalize the place where you ll find the command to run/test/build/publish.
It should be a one-liner calling a more complex tool to implement and realize the job.