Make "mix new" add Hex info to mix.exs and README?

[Henrik N]

I just wrote my first hex package and felt the experience was a bit less smooth than it could have been, because the mix.exs in my generated project did not include the required/recommended values for a Hex project: description and  package.{licenses,contributors,links}.

Would also have been nice for the README to get a boilerplate paragraph about how to install this lib as a dependency.

I wouldn't be surprised if some or all of these omissions are intentional with good reasons behind it, so I thought I'd ask before making a pull request.

If it is intentionally omitted, could it make sense to add some flag like mix new my_project --hex that adds this stuff? I guess another option would be a separate command similar to mix phoenix.new , but if you need to install it separately, that would of course be a bit less convenient.

I'd love for the "my first hex" experience to be super smooth :)

[José Valim]

What is required to setup a hex page that is missing in mix.exs? The answer depends a lot on how much we can automate in the first place.

> Would also have been nice for the README to get a boilerplate paragraph about how to install this lib as a dependency.

This is already part of Elixir 1.1. :)

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Director of R&D

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/c7d912b4-beec-45d1-bf31-5afffa67f55c%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Henrik N]

On Saturday, September 5, 2015 at 10:06:22 AM UTC+2, José Valim wrote:

What is required to setup a hex page that is missing in mix.exs? The answer depends a lot on how much we can automate in the first place.

What is missing is :description and a :package property with :contributors, :licenses and :links.

Trying to "mix hex.publish" without these gives you a warning:

    WARNING! Missing metadata fields: description, licenses, contributors, links

I don't mean we necessarily have to automatically fill out those fields with correct values – I would be happy to just have them default to empty values, perhaps with a helpful comment.

 

> Would also have been nice for the README to get a boilerplate paragraph about how to install this lib as a dependency.

This is already part of Elixir 1.1. :)

Oh, glorious :)

[José Valim]

If Hex can go without those fields, I wouldn't add them. I would prefer to have the minimum required than add boilerplate for many things the user does not need to worry about when they first look at it.

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Director of R&D

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/86361c9b-d8e7-417b-a3c0-d1ebe7c8aef9%40googlegroups.com.

[eksperimental]

One request that I would like to make, and that I found trouble dealing
the very first time I had to hack into an Elixir project is that the
format for the data in the helpers in mix.exs could be simplified,

so instead of having

def project do
[app: :foo,
version: "0.0.1",
elixir: "~> 1.1-dev",
build_embedded: Mix.env == :prod,
start_permanent: Mix.env == :prod,
deps: deps]
end

def application do
[applications: [:logger]]
end


I think it will be clearer to have:

def project do
[
app: :foo,
version: "0.0.1",
elixir: "~> 1.1-dev",
build_embedded: Mix.env == :prod,
start_permanent: Mix.env == :prod,
deps: deps,
]
end

def application do
[
applications: [:logger, ],
]
end

This automatically tells the user that each line is one item, leaving
the delimiters of the list out.
It also adds a comma at the end of the last item in the list,
suggesting the list can be extended. See
https://github.com/elixir-lang/elixir/pull/3091 for more info.
An extra benefit that comes for free, is that it uses even number of
spaces, right now the second line in project uses odd number, which is
hard to indent with some text-editors.

On Sat, 5 Sep 2015 10:25:31 +0200
José Valim <jose....@plataformatec.com.br> wrote:

> If Hex can go without those fields, I wouldn't add them. I would
> prefer to have the minimum required than add boilerplate for many
> things the user does not need to worry about when they first look at
> it.
>
>
>

> *José Valim*

> > <https://groups.google.com/d/msgid/elixir-lang-core/86361c9b-d8e7-417b-a3c0-d1ebe7c8aef9%40googlegroups.com?utm_medium=email&utm_source=footer>
> > .

[Andrea Leopardi]

Can't agree more with eksperimental on this one. I change from the default one to one item per line with brackets on separate lines for pretty much every project.

Andrea Leopardi

an.le...@gmail.com

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/20150905165020.2b5b17a8.eksperimental%40autistici.org.

[Henrik N]

On Saturday, September 5, 2015 at 10:25:51 AM UTC+2, José Valim wrote:

If Hex can go without those fields, I wouldn't add them. I would prefer to have the minimum required than add boilerplate for many things the user does not need to worry about when they first look at it.

That's fair, but how about a `mix new my_project --hex` to add them? Even if they're not mandatory, they're "highly recommended" according to https://hex.pm/docs/publish, and I think it could make sense to encourage their use.

eksperimental, Andrea: While I very much agree (and have tried to argue the point here: https://github.com/phoenixframework/phoenix/pull/1007), I think it could be a good idea for you to start another discussion thread about that, to keep this one focused :)

[José Valim]

I would really like to avoid adding more options for something that will be as simple as adding:

    description: "",

    package: [...]

to your mix.exs file. Generators are a learning tool and we must focus on what is the most important at first, they are not there to write all the code.

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Director of R&D

[Henrik N]

On Saturday, September 5, 2015 at 1:07:25 PM UTC+2, José Valim wrote:

I would really like to avoid adding more options for something that will be as simple as adding:

    description: "",

    package: [...]

to your mix.exs file. Generators are a learning tool and we must focus on what is the most important at first, they are not there to write all the code.

As someone who wrote my first hex package yesterday, I would have found that a much smoother experience. But if you feel generating that boilerplate is not the way to go, I think some tweaks to https://hex.pm/docs/publish could go a long way – it currently explains in words the nested package structure to add, for example, and the code examples is further down on the page, so I tried to parse that text before I even saw the code example. I'll try to get around to make a pull request to the docs if they're on GitHub.

Still, even if the docs are super clear, I would find it less convenient to reference them when creating a new hex package, compared to just getting a helpful template generated. I think "bundle gem" gets this right – I'm actively delighted every time I use it and notice how they've taken care of all the boilerplate, leaving me a minimum of yaks to shave :)

[José Valim]

As someone who wrote my first hex package yesterday, I would have found that a much smoother experience. But if you feel generating that boilerplate is not the way to go, I think some tweaks to https://hex.pm/docs/publish could go a long way – it currently explains in words the nested package structure to add, for example, and the code examples is further down on the page, so I tried to parse that text before I even saw the code example. I'll try to get around to make a pull request to the docs if they're on GitHub.

Yes, if the docs can be improved, please do send pull requests. 

Maybe a good compromise is to provide a link in the README to the Hex publish docs, so newcomers at least do not have to search how to publish the package on the first page. I will add such a note before I push 1.1.0-beta.

[Henrik N]

That sounds like a great idea – I'm okay settling for that ;) Thank you, José! <3

[Eric Meadows-Jönsson]

Please send a PR for the publish docs if you think they can be made more clear.

I don't want to add the package boilerplate to `mix new` because unlike all the other boilerplate generated we cannot give good defaults, they would just be empty strings. It would also make the missing fields warning Hex shows useless so we run an even greater risk of package authors not filling out the fields.

--

You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/a297f1e8-d454-470d-8fd2-eaca01061b61%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

Eric Meadows-Jönsson

[Henrik Nyh]

On Sat, Sep 5, 2015 at 3:38 PM, Eric Meadows-Jönsson <eric.meado...@gmail.com> wrote:

I don't want to add the package boilerplate to `mix new` because unlike all the other boilerplate generated we cannot give good defaults, they would just be empty strings. It would also make the missing fields warning Hex shows useless so we run an even greater risk of package authors not filling out the fields.

That's a very good argument. Thank you. Yeah, I'll try to make a pull request for the docs.

[Paul Schoenfelder]

Just a thought, but what about generating them, but commented out? That way a new project shows you what to start fleshing out when you have the details down, and saves you having to reference the documentation. I'm with José and Eric on this, but it's a compromise solution that I think addresses both concerns.

Paul

--

You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAL%2B%3DsuPJ07V9_W5eQRESraeo-ZNGsxkhWLGtRt1y7_-bkGifTQ%40mail.gmail.com.

[Gabriel Jaldon]

I like Paul's idea of generating defaults but in comment form. They sound like a good compromise and helps make it easier for Elixir users to publish packages.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAK%3D%2B-TvvQPHvH4y_Ag1FxfdJOGmODQFSgK1fDmoC5ZGTaAiuhw%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

--

Gabe Jaldon

[Michał Muskała]

The problem is, even when commented out, what is a good default author name?

> https://groups.google.com/d/msgid/elixir-lang-core/CAHi9bZqaV64WNfSX9wAAKwjvpphh5EFN%2BVUwozoKSMRapMSxVA%40mail.gmail.com.

[Paul Schoenfelder]

I think in commented out form, empty strings are fine, it makes it clear that it's expecting you to provide an author name as a string if you decide to uncomment it. I don't think default values (other than empty strings or equivalent) should be generated for commented out properties.

Paul

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAGAFNpnoW2O9y%3D350YcHok_qatyAuizYpPHaD1A%2B%3DsJj%2B8%3DKJg%40mail.gmail.com.

[José Valim]

The files generated today already rely on comments to explain how dependencies work, configuration, etc. and adding comments about packaging is still a distraction when developers are getting started and most focus on other things.



--

[Booker Bense]

It should crash in flames if you uncomment default values without changing it. Default

values must cause an error. 

I'd much rather see a mix hex.prepare task that added these in later if 

needed. Likely by then you could get useful data out of git. 

The vast majority of mix projects will not end up in hex. Adding stuff that 

isn't needed to a file that is already somewhat complex ( comments or not),

seems unfriendly to the beginner. 

- Booker C. Bense 

[Henrik N]

I've written a few Hex packages since I started this thread, and I keep finding it a bit inconvenient and developer-unfriendly that we're not helping out more with the metadata fields.

Here's a proposal that attempts to address the concerns that have been raised:

* Make it a separate task from "mix new", e.g. "mix hex.new".

  That way, projects that aren't intended to become packages won't be cluttered. Anyone who doesn't know of the new task gets the current experience. Anyone who knows of it can get a better experience.

* Have it add the Hex metadata fields, but commented out.

  That way, there's little risk of the default data being pushed to Hex.

  The values could be empty if people are concerned that trying to guess or provide common values would be a bad idea.

Optionally:

* By having a separate generation task, we could also help out more with the README. It currently says "If available in Hex", for example.

What do you think?

[José Valim]

It still goes back to the previous concerns: I don't want to add more information to the mix.exs file. One option is to put even more information in the README that would tell you how to publish the package or have hex.publish be a bit smarter: if you run "mix hex.publish" and there is no :package key, we could output some code samples and a bit more information on how to get it published.

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Director of R&D

--

You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/b4645f34-5307-4c46-9004-aa8abdb2b8ee%40googlegroups.com.

[Andrea Leopardi]

I love the idea of making `mix hex.publish` more helpful by outputting a sample config when there's no :package key, so +1 for that!

Andrea Leopardi

an.le...@gmail.com

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4JDNu8dYOB_XdSeaP5Fr4frSbW7pFs_zSdogtg05qN0hA%40mail.gmail.com.

[Henrik Nyh]

On 21 Nov 2015, at 15:41, José Valim <jose....@plataformatec.com.br> wrote:

It still goes back to the previous concerns: I don't want to add more information to the mix.exs file.

Even if someone explicitly says they intend to publish to Hex, by using a separate task like "mix hex.new"? I'm afraid I don't follow. What is the downside to that, if they're going to need to add it in anyway?

One option is to put even more information in the README that would tell you how to publish the package or have hex.publish be a bit smarter: if you run "mix hex.publish" and there is no :package key, we could output some code samples and a bit more information on how to get it published.

That would be an improvement for sure. If generating it into the mix.exs file is not something we want to do, this would be nice.

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Director of R&D

On Sat, Nov 21, 2015 at 8:15 PM, Henrik N <hen...@nyh.se> wrote:

I've written a few Hex packages since I started this thread, and I keep finding it a bit inconvenient and developer-unfriendly that we're not helping out more with the metadata fields.

Here's a proposal that attempts to address the concerns that have been raised:

* Make it a separate task from "mix new", e.g. "mix hex.new".

  That way, projects that aren't intended to become packages won't be cluttered. Anyone who doesn't know of the new task gets the current experience. Anyone who knows of it can get a better experience.

* Have it add the Hex metadata fields, but commented out.

  That way, there's little risk of the default data being pushed to Hex.

  The values could be empty if people are concerned that trying to guess or provide common values would be a bad idea.

Optionally:

* By having a separate generation task, we could also help out more with the README. It currently says "If available in Hex", for example.

What do you think?

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/b4645f34-5307-4c46-9004-aa8abdb2b8ee%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

You received this message because you are subscribed to a topic in the Google Groups "elixir-lang-core" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/elixir-lang-core/bA9fR19JRTc/unsubscribe.
To unsubscribe from this group and all its topics, send an email to elixir-lang-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4JDNu8dYOB_XdSeaP5Fr4frSbW7pFs_zSdogtg05qN0hA%40mail.gmail.com.