Erlang checklists

classic Classic list List threaded Threaded
11 messages Options
Reply | Threaded
Open this post in threaded view
|

Erlang checklists

Lloyd R. Prentice-2

Hello,

 

With the generous help of Frank Muller, I recently created the erlPress_core repository on GitHub.

 

Make a few blunders along the way. Still feel shaky about my responsibilities for nurturing the repository.

 

So I'd like to create and share a step_by_step checklist for other Erlang noobs preparing to share code on GitHub with the Erlang community.

 

Please send my your ideas.

 

I'd like to do the same for releasing Erlang applications into production, but I'll hold on that for another time.

 

Many thanks,

 

LRP

 

 

*********************************************
My books:

THE GOSPEL OF ASHES
http://thegospelofashes.com

Strength is not enough. Do they have the courage
and the cunning? Can they survive long enough to
save the lives of millions?

FREEIN' PANCHO
http://freeinpancho.com

A community of misfits help a troubled boy find his way

AYA TAKEO
http://ayatakeo.com

Star-crossed love, war and power in an alternative
universe

Available through Amazon or by request from your
favorite bookstore


**********************************************


_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Erlang checklists

Brujo Benavides-3
Hi Lloyd,


Cheers!

On 28 Oct 2018, at 19:39, [hidden email] wrote:

Hello,

 

With the generous help of Frank Muller, I recently created the erlPress_core repository on GitHub.

 

Make a few blunders along the way. Still feel shaky about my responsibilities for nurturing the repository.

 

So I'd like to create and share a step_by_step checklist for other Erlang noobs preparing to share code on GitHub with the Erlang community.

 

Please send my your ideas.

 

I'd like to do the same for releasing Erlang applications into production, but I'll hold on that for another time.

 

Many thanks,

 

LRP

 

 

*********************************************
My books:

THE GOSPEL OF ASHES
http://thegospelofashes.com

Strength is not enough. Do they have the courage
and the cunning? Can they survive long enough to
save the lives of millions?

FREEIN' PANCHO
http://freeinpancho.com

A community of misfits help a troubled boy find his way

AYA TAKEO
http://ayatakeo.com

Star-crossed love, war and power in an alternative
universe

Available through Amazon or by request from your
favorite bookstore


**********************************************
_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions


_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Erlang checklists

Roger Lipscombe-2
On 29 October 2018 at 12:04, Brujo Benavides <[hidden email]> wrote:
>
> Hi Lloyd,
>
> This is the checklist we have at Inaka: https://github.com/inaka/guidelines/blob/master/OPEN-SOURCE.md
>

> It's has a clear and useful README.md

*It*

That aside ;-), one of my personal bugbears about README files is that
not enough of them tell me what the project *is*.

For example:

"Project MooCow aims to be performant, extensible and simple to use."
Great, but is it a database, an HTTP client, a BDD tool or what?

Cheers,
Roger.
_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Erlang checklists

Loïc Hoguin-3
On 10/29/18 1:12 PM, Roger Lipscombe wrote:

> On 29 October 2018 at 12:04, Brujo Benavides <[hidden email]> wrote:
>>
>> Hi Lloyd,
>>
>> This is the checklist we have at Inaka: https://github.com/inaka/guidelines/blob/master/OPEN-SOURCE.md
>>
>
>> It's has a clear and useful README.md
>
> *It*
>
> That aside ;-), one of my personal bugbears about README files is that
> not enough of them tell me what the project *is*.
>
> For example:
>
> "Project MooCow aims to be performant, extensible and simple to use."
> Great, but is it a database, an HTTP client, a BDD tool or what?

The first sentence of the README file should not only say what the
project is, but also persuade people to use your project instead of one
of the alternatives. In other words it should clarify who your project
is for.

For example:

* MooCow is an HTTP client for Erlang.
* MooCow is an enterprise-ready HTTP client for Erlang.

This simple addition can be interpreted a number of ways, and sometimes
users will misinterpret, but it suggests that it does more things than a
plain HTTP client, for example export metrics and/or allow monitoring
tools to be plugged into it.

Don't make the sentence too long though, limit to 2 or 3 attributes that
make the biggest difference compared to other projects, or that are the
biggest strengths if there are no similar projects.

That first sentence should be used everywhere where a short description
is to be provided.

Remember, we form our opinions on most things in a split second very
early on when we are exposed to something new. The more alternatives
there are the most important influencing that split second becomes.

Cheers,

--
Loïc Hoguin
https://ninenines.eu
_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Erlang checklists

Lloyd R. Prentice-2
In reply to this post by Brujo Benavides-3

Hi All,

 

Terrific list, Brujo!

 

Mind if I pare it down for Erlang and add a few very fundamental items that experienced Erlang programmers take for granted, but newcomers may miss:

 

--  Nicely formatted module header (Is there a convention? Thoughts welcome)

--  Uncomment -exort(xxx and and comment -configure(xxx lines

-- @doc and -spec documentation of functions (Just exported or all in module?)

-- Anything else we're missing?

 

Among other things, how should versions be handled in module headers given that we have an application version and perhaps a mix of module versions?

 

Roger and Loïc:

 

I couldn't agree with you more about specific statement of what the code does and who it would benefit. And Loïc's other tips are well taken.

 

I'll try to work them all in and send updated checklist anon.

 

Thanks,

 

Lloyd

 

-----Original Message-----
From: "Brujo Benavides" <[hidden email]>
Sent: Monday, October 29, 2018 8:04am
To: [hidden email]
Cc: "[hidden email]" <[hidden email]>
Subject: Re: [erlang-questions] Erlang checklists

Hi Lloyd,
Cheers!

On 28 Oct 2018, at 19:39, [hidden email] wrote:

Hello,

 

With the generous help of Frank Muller, I recently created the erlPress_core repository on GitHub.

 

Make a few blunders along the way. Still feel shaky about my responsibilities for nurturing the repository.

 

So I'd like to create and share a step_by_step checklist for other Erlang noobs preparing to share code on GitHub with the Erlang community.

 

Please send my your ideas.

 

I'd like to do the same for releasing Erlang applications into production, but I'll hold on that for another time.

 

Many thanks,

 

LRP

 

 

*********************************************
My books:

THE GOSPEL OF ASHES
http://thegospelofashes.com

Strength is not enough. Do they have the courage
and the cunning? Can they survive long enough to
save the lives of millions?

FREEIN' PANCHO
http://freeinpancho.com

A community of misfits help a troubled boy find his way

AYA TAKEO
http://ayatakeo.com

Star-crossed love, war and power in an alternative
universe

Available through Amazon or by request from your
favorite bookstore


**********************************************
_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions

_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Erlang checklists

Dmytro Lytovchenko
With all that is mentioned by Brujo before, ...

Think about your future new user. Some empathy (i have empatic character, and i know this first hand you see).

  • What are your new user's first steps when he opened your library's web page?
  • Will he see a description? (many libraries have really bad descriptions) Some welcoming examples and a quick start?
  • What will he take as his first hello_your_library? And maybe some advanced examples too?
  • Where will he come to read the docs?
  • (bonus points) A community discussion board or something like that? Issues page on Github that is well maintained is a good first step.

On Mon, 29 Oct 2018 at 22:28, <[hidden email]> wrote:

Hi All,

 

Terrific list, Brujo!

 

Mind if I pare it down for Erlang and add a few very fundamental items that experienced Erlang programmers take for granted, but newcomers may miss:

 

--  Nicely formatted module header (Is there a convention? Thoughts welcome)

--  Uncomment -exort(xxx and and comment -configure(xxx lines

-- @doc and -spec documentation of functions (Just exported or all in module?)

-- Anything else we're missing?

 

Among other things, how should versions be handled in module headers given that we have an application version and perhaps a mix of module versions?

 

Roger and Loïc:

 

I couldn't agree with you more about specific statement of what the code does and who it would benefit. And Loïc's other tips are well taken.

 

I'll try to work them all in and send updated checklist anon.

 

Thanks,

 

Lloyd

 

-----Original Message-----
From: "Brujo Benavides" <[hidden email]>
Sent: Monday, October 29, 2018 8:04am
To: [hidden email]
Cc: "[hidden email]" <[hidden email]>
Subject: Re: [erlang-questions] Erlang checklists

Hi Lloyd,
Cheers!

On 28 Oct 2018, at 19:39, [hidden email] wrote:

Hello,

 

With the generous help of Frank Muller, I recently created the erlPress_core repository on GitHub.

 

Make a few blunders along the way. Still feel shaky about my responsibilities for nurturing the repository.

 

So I'd like to create and share a step_by_step checklist for other Erlang noobs preparing to share code on GitHub with the Erlang community.

 

Please send my your ideas.

 

I'd like to do the same for releasing Erlang applications into production, but I'll hold on that for another time.

 

Many thanks,

 

LRP

 

 

*********************************************
My books:

THE GOSPEL OF ASHES
http://thegospelofashes.com

Strength is not enough. Do they have the courage
and the cunning? Can they survive long enough to
save the lives of millions?

FREEIN' PANCHO
http://freeinpancho.com

A community of misfits help a troubled boy find his way

AYA TAKEO
http://ayatakeo.com

Star-crossed love, war and power in an alternative
universe

Available through Amazon or by request from your
favorite bookstore


**********************************************
_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions

_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Erlang checklists

scott ribe
On Oct 29, 2018, at 4:36 PM, Dmytro Lytovchenko <[hidden email]> wrote:
>
> Think about your future new user. Some empathy (i have empatic character, and i know this first hand you see).
>
> • What are your new user's first steps when he opened your library's web page?
> • Will he see a description? (many libraries have really bad descriptions) Some welcoming examples and a quick start?
> • What will he take as his first hello_your_library? And maybe some advanced examples too?
> • Where will he come to read the docs?
> • (bonus points) A community discussion board or something like that? Issues page on Github that is well maintained is a good first step.


- Follow your build instructions and verify that they actually work!

I hit this one just today, 2 errors in the build instructions that could have stumped a newbie. (Not an Erlang project, FYI.)


_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Erlang checklists

Brujo Benavides-3
In reply to this post by Lloyd R. Prentice-2
Of course, you are free to do whatever you want, Lloyd. PRs are also welcomed :P

On Mon, 29 Oct 2018 at 19:27 <[hidden email]> wrote:

Hi All,

 

Terrific list, Brujo!

 

Mind if I pare it down for Erlang and add a few very fundamental items that experienced Erlang programmers take for granted, but newcomers may miss:

 

--  Nicely formatted module header (Is there a convention? Thoughts welcome)

--  Uncomment -exort(xxx and and comment -configure(xxx lines

-- @doc and -spec documentation of functions (Just exported or all in module?)

-- Anything else we're missing?

 

Among other things, how should versions be handled in module headers given that we have an application version and perhaps a mix of module versions?

 

Roger and Loïc:

 

I couldn't agree with you more about specific statement of what the code does and who it would benefit. And Loïc's other tips are well taken.

 

I'll try to work them all in and send updated checklist anon.

 

Thanks,

 

Lloyd

 

-----Original Message-----
From: "Brujo Benavides" <[hidden email]>
Sent: Monday, October 29, 2018 8:04am
To: [hidden email]
Cc: "[hidden email]" <[hidden email]>
Subject: Re: [erlang-questions] Erlang checklists

Hi Lloyd,
Cheers!

On 28 Oct 2018, at 19:39, [hidden email] wrote:

Hello,

 

With the generous help of Frank Muller, I recently created the erlPress_core repository on GitHub.

 

Make a few blunders along the way. Still feel shaky about my responsibilities for nurturing the repository.

 

So I'd like to create and share a step_by_step checklist for other Erlang noobs preparing to share code on GitHub with the Erlang community.

 

Please send my your ideas.

 

I'd like to do the same for releasing Erlang applications into production, but I'll hold on that for another time.

 

Many thanks,

 

LRP

 

 

*********************************************
My books:

THE GOSPEL OF ASHES
http://thegospelofashes.com

Strength is not enough. Do they have the courage
and the cunning? Can they survive long enough to
save the lives of millions?

FREEIN' PANCHO
http://freeinpancho.com

A community of misfits help a troubled boy find his way

AYA TAKEO
http://ayatakeo.com

Star-crossed love, war and power in an alternative
universe

Available through Amazon or by request from your
favorite bookstore


**********************************************
_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
--
elbrujohalcon @ iPhone

_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Erlang checklists

Brujo Benavides-3
In reply to this post by Lloyd R. Prentice-2
About your items:
- not sure about module headers. But yeah, @doc in every module is a good guideline
- no idea what you mean by this. I've never seen a -configure line in an Erlang module
- just for exported ones I would say

On Mon, 29 Oct 2018 at 19:27 <[hidden email]> wrote:

Hi All,

 

Terrific list, Brujo!

 

Mind if I pare it down for Erlang and add a few very fundamental items that experienced Erlang programmers take for granted, but newcomers may miss:

 

--  Nicely formatted module header (Is there a convention? Thoughts welcome)

--  Uncomment -exort(xxx and and comment -configure(xxx lines

-- @doc and -spec documentation of functions (Just exported or all in module?)

-- Anything else we're missing?

 

Among other things, how should versions be handled in module headers given that we have an application version and perhaps a mix of module versions?

 

Roger and Loïc:

 

I couldn't agree with you more about specific statement of what the code does and who it would benefit. And Loïc's other tips are well taken.

 

I'll try to work them all in and send updated checklist anon.

 

Thanks,

 

Lloyd

 

-----Original Message-----
From: "Brujo Benavides" <[hidden email]>
Sent: Monday, October 29, 2018 8:04am
To: [hidden email]
Cc: "[hidden email]" <[hidden email]>
Subject: Re: [erlang-questions] Erlang checklists

Hi Lloyd,
Cheers!

On 28 Oct 2018, at 19:39, [hidden email] wrote:

Hello,

 

With the generous help of Frank Muller, I recently created the erlPress_core repository on GitHub.

 

Make a few blunders along the way. Still feel shaky about my responsibilities for nurturing the repository.

 

So I'd like to create and share a step_by_step checklist for other Erlang noobs preparing to share code on GitHub with the Erlang community.

 

Please send my your ideas.

 

I'd like to do the same for releasing Erlang applications into production, but I'll hold on that for another time.

 

Many thanks,

 

LRP

 

 

*********************************************
My books:

THE GOSPEL OF ASHES
http://thegospelofashes.com

Strength is not enough. Do they have the courage
and the cunning? Can they survive long enough to
save the lives of millions?

FREEIN' PANCHO
http://freeinpancho.com

A community of misfits help a troubled boy find his way

AYA TAKEO
http://ayatakeo.com

Star-crossed love, war and power in an alternative
universe

Available through Amazon or by request from your
favorite bookstore


**********************************************
_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
--
elbrujohalcon @ iPhone

_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Erlang checklists

Roger Lipscombe-2
In reply to this post by Lloyd R. Prentice-2
On 29 October 2018 at 22:27,  <[hidden email]> wrote:
> Among other things, how should versions be handled in module headers given
> that we have an application version and perhaps a mix of module versions?

They shouldn't. There's no need for module versions to vary
independently of the application version. And there's no need to have
them (I assume you mean as comments) in module headers. That's what
source control's for.

Just generate the application version from the same
source-control-derived value. For modules, you can just use Erlang's
default MD5 scheme for module versions. Or you can make it the same as
the application version.

We use https://github.com/electricimp/vsn_transform, but note that --
depending on what you use to generate the version string -- you might
end up with a non-reproducible build (see
https://reproducible-builds.org/).
_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Erlang checklists

Lloyd R. Prentice-2
In reply to this post by Brujo Benavides-3

Sorry, late night finger flub.

 

I meant -compile(export all).

 

Good ideas coming together. I'll try to summarize what we have so far anon.

 

Best wishes to all.

 

Lloyd

 

 

-----Original Message-----
From: "Brujo Benavides" <[hidden email]>
Sent: Monday, October 29, 2018 9:31pm
To: [hidden email]
Cc: "[hidden email]" <[hidden email]>
Subject: Re: [erlang-questions] Erlang checklists

About your items:
- not sure about module headers. But yeah, @doc in every module is a good guideline
- no idea what you mean by this. I've never seen a -configure line in an Erlang module
- just for exported ones I would say

On Mon, 29 Oct 2018 at 19:27 <[hidden email]> wrote:

Hi All,

 

Terrific list, Brujo!

 

Mind if I pare it down for Erlang and add a few very fundamental items that experienced Erlang programmers take for granted, but newcomers may miss:

 

--  Nicely formatted module header (Is there a convention? Thoughts welcome)

--  Uncomment -exort(xxx and and comment -configure(xxx lines

-- @doc and -spec documentation of functions (Just exported or all in module?)

-- Anything else we're missing?

 

Among other things, how should versions be handled in module headers given that we have an application version and perhaps a mix of module versions?

 

Roger and Loïc:

 

I couldn't agree with you more about specific statement of what the code does and who it would benefit. And Loïc's other tips are well taken.

 

I'll try to work them all in and send updated checklist anon.

 

Thanks,

 

Lloyd

 

-----Original Message-----
From: "Brujo Benavides" <[hidden email]>
Sent: Monday, October 29, 2018 8:04am
To: [hidden email]
Cc: "[hidden email]" <[hidden email]>
Subject: Re: [erlang-questions] Erlang checklists

Hi Lloyd,
Cheers!

On 28 Oct 2018, at 19:39, [hidden email] wrote:

Hello,

 

With the generous help of Frank Muller, I recently created the erlPress_core repository on GitHub.

 

Make a few blunders along the way. Still feel shaky about my responsibilities for nurturing the repository.

 

So I'd like to create and share a step_by_step checklist for other Erlang noobs preparing to share code on GitHub with the Erlang community.

 

Please send my your ideas.

 

I'd like to do the same for releasing Erlang applications into production, but I'll hold on that for another time.

 

Many thanks,

 

LRP

 

 

*********************************************
My books:

THE GOSPEL OF ASHES
http://thegospelofashes.com

Strength is not enough. Do they have the courage
and the cunning? Can they survive long enough to
save the lives of millions?

FREEIN' PANCHO
http://freeinpancho.com

A community of misfits help a troubled boy find his way

AYA TAKEO
http://ayatakeo.com

Star-crossed love, war and power in an alternative
universe

Available through Amazon or by request from your
favorite bookstore


**********************************************
_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
--
elbrujohalcon @ iPhone

_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions