Smalltalk › Pharo › Pharo Smalltalk Developers

Default package comment

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

14 messages Options

Sergio Fedi

Default package comment

Hi guys,

we are adding comments to packages and we would like a feedback from the community.

What do you suggest for the default package comment?

Sergio Fedi

Re: Default package comment

Ok, I came up with this default comment.

Let's see what you guys think of it:

This is a default comment for a package.

To create a new one follow these guidelines:

- Make the first line a one line description of the package and its purpose.

- Describe with a more detailed description the problem solved and how the package works

- Describe how to use the package with code snippets and what classes are the ones you'll use normally

- Mention any side effect that may come from installing or uninstalling the package

- Write information from the package like author, contact, repository, date of creation, etc.

PD: I know the above should be modelled in the Manifest of the Package, but it's better to have it in the comment while we don't have implemented them.

Sean P. DeNigris

Re: Default package comment

Administrator

Sergio Fedi wrote

Let's see what you guys think of it:

Why not?! I'm sure we'll tweak it as we start using it. The only thing is that maybe specific meta info like author, contact, website, repository, and date of creation should go in separate methods so that they can be dealt with programatically (e.g. send an email to the contact person). We can have them appended to the appropriate place when the comment is shown in a tool.

Cheers,
Sean

Eliot Miranda-2

Re: Default package comment

In reply to this post by Sergio Fedi

Hi Sergio,

On Fri, May 15, 2015 at 6:28 AM, Sergio Fedi <[hidden email]> wrote:

Ok, I came up with this default comment.

Let's see what you guys think of it:

This is a default comment for a package.

To create a new one follow these guidelines:

- Make the first line a one line description of the package and its purpose.
- Describe with a more detailed description the problem solved and how the package works
- Describe how to use the package with code snippets and what classes are the ones you'll use normally
- Mention any side effect that may come from installing or uninstalling the package
- Write information from the package like author, contact, repository, date of creation, etc.

I would add:

- describe how to load the package, including any additional dependencies, version requirements, etc.

PD: I know the above should be modelled in the Manifest of the Package, but it's better to have it in the comment while we don't have implemented them.

best,

Eliot

Sergio Fedi

Re: Default package comment

In reply to this post by Sean P. DeNigris

> > Let's see what you guys think of it:
>
> Why not?! I'm sure we'll tweak it as we start using it. The only thing is
> that maybe specific meta info like author, contact, website, repository, and
> date of creation should go in separate methods so that they can be dealt
> with programatically (e.g. send an email to the contact person). We can have
> them appended to the appropriate place when the comment is shown in a tool.

I know, that's what I commented in the PD.

But for now, until the author and other data is not in differente methods,

don't you think it's better to have it in the comment rather than nowhere else?

Sergio Fedi

Re: Default package comment

In reply to this post by Eliot Miranda-2

> I would add:
>
> - describe how to load the package, including any additional dependencies, version requirements, etc.

Even though to read the comment you have to already have done all of that?

(i.e. to read the comment you have to have the package already loaded in the image)

The dependencies, requirements, etc could be calculated from the Metacello dependencies.

Sean P. DeNigris

Re: Default package comment

Administrator

In reply to this post by Sergio Fedi

Sergio Fedi wrote

But for now, until the author and other data is not in differente methods,
don't you think it's better to have it in the comment rather than nowhere
else?

You're inventing it, why not invent it as meta-data. At the start of something, there is a unique opportunity because no one has habits around it yet. If you establish "throw it all in the comment", that's what everyone will get used to. What's the downside of putting no-op or sample methods in the superclass to show the API? Just like the catalog methods for the whole project... which brings an interesting point.

Since presumably the project will store this info, does it belong at the package level?
- For example, what does it mean to be the author of a package? The original author? The author of the idea?
- What about the creation timestamp? We have this info in MC, so do you mean the date of the initial commit?
- Contact probably belongs at the project level
- Repository is somewhat dangerous because it duplicates domain info in text, which will usually be out of date. It would be better to somehow get this from MC. Do many people really pass around MC files? Presumably if you have the mcz you know where it lives. Unless we could *set* this info from MC so it would always be in sync...

Anyway, I agree that anything is better than what we have now (i.e. nothing!) but also that we should take a moment to really think about a new feature because we may have to live with these decisions for a long time...

Cheers,
Sean

Eliot Miranda-2

Re: Default package comment

In reply to this post by Sergio Fedi

On Fri, May 15, 2015 at 9:40 AM, Sergio Fedi <[hidden email]> wrote:

> I would add:
>
> - describe how to load the package, including any additional dependencies, version requirements, etc.

Even though to read the comment you have to already have done all of that?

I expect a package comment will be browsable from a repository. I expect one of the main uses will be reading package comments of packages I'm curious about loading.

(i.e. to read the comment you have to have the package already loaded in the image)

The dependencies, requirements, etc could be calculated from the Metacello dependencies.

Not everything is loaded through Metacello. Don't assume a single configuration. Make the scheme as general as possible.

best,

Eliot

Sergio Fedi

Re: Default package comment

Personally, I do not fear to change the comment implementation later.

That's what Smalltalk is good at.

But that doesn't mean it's the right choice :)

The thing is that we can go full speed with this and make comments for:

oneLineSummary

longDescription

usageDescription

preInstallComment

postInstallComment

authorshipText

contactDescription

creationDate

lastUpdateDate

and a long etcetera

Or we could go beyond this and define set of properties, each one with it's priority to be shown and some way to define the order of rendering.

Problem is: where to draw the line?

My initial strategy was to have comments and then model the commonalities of all package comments away to the appropiate method/variable/data

Let's keep discussing this.

demarey

Re: Default package comment

Le 15 mai 2015 à 22:39, Sergio Fedi a écrit :

>
> Personally, I do not fear to change the comment implementation later.
> That's what Smalltalk is good at.

+1. But the most difficult thing is not to change the implementation but all its usage.
if people start to use a feature and you change the way to use it after, it is more difficult to update all users of the feature.

> But that doesn't mean it's the right choice :)
>
> The thing is that we can go full speed with this and make comments for:
>
> oneLineSummary
> longDescription
> usageDescription

ok

> preInstallComment
> postInstallComment

what is that? if it is Smalltalk code to run before/after the installation, it should not be in the comment but in a separated method.
Pharo misses a package setUp and tearDown methods.

> authorshipText
> contactDescription
> creationDate
> lastUpdateDate

This information is meta-information on a package and should not be lost in the package comment.

> and a long etcetera
>
> Or we could go beyond this and define set of properties, each one with it's priority to be shown and some way to define the order of rendering.
>
> Problem is: where to draw the line?
>
> My initial strategy was to have comments and then model the commonalities of all package comments away to the appropiate method/variable/data

I already started to work on some specific package meta-data.
As I wrote before, for now, I store it in the PackageManifest because Monticello does not have a good support for meta-data.
But anyway, we could just see that as an "implementation details".
What I think is important is not to work directly with the PackageManifest but having an object manipulating it and able to answer to selectors like:
MyPackage>>description
MyPackage>>description: aText
...
MyPackage>>aMetadata
MyPackage>>aMetadata: value

I work on a spec widget to edit some package meta-data.
Maybe you could do the same to be able to present other meta-data than the package comment from Nautilus. It is more work and can just come for a second version.

Regards,
Christophe

smime.p7s (5K) Download Attachment

Sergio Fedi

Re: Default package comment

> > Personally, I do not fear to change the comment implementation later.
> > That's what Smalltalk is good at.
>
> +1. But the most difficult thing is not to change the implementation but all its usage.
> if people start to use a feature and you change the way to use it after, it is more difficult to update all users of the feature.

Problem is, this feature is not used now because it doesn't exist.

Bottom line is:

If the future usage problem is about what to put in the default comment, It's ok for me to change it however we decide.

If the future usage problem is about what other metadata we put con the Manifest then it is irrelevant for this issue.

> > preInstallComment
> > postInstallComment
>
> what is that? if it is Smalltalk code to run before/after the installation, it should not be in the comment but in a separated method.
> Pharo misses a package setUp and tearDown methods.

These are comments relating to thing you have to be aware of before installing and after installing the package.

For example, a behaviour changed on some objects. A new option on a menu. Another package that does not "get along" with this package.

Things that are not code, but are relevant either before or after the loading of a package.

> > authorshipText
> > contactDescription
> > creationDate
> > lastUpdateDate
>
> This information is meta-information on a package and should not be lost in the package comment.

Exactly.

Except that when you can't put it anywhere else, it usually ends up in the comment.

(my argument is: as long as you don't have anywhere else to put certain info, it's better to have it somewhere rather than nowhere, so you could suggest that in the default comment)

> > My initial strategy was to have comments and then model the commonalities of all package comments away to the appropiate method/variable/data
>
> I already started to work on some specific package meta-data.
> As I wrote before, for now, I store it in the PackageManifest because Monticello does not have a good support for meta-data.
> But anyway, we could just see that as an "implementation details".
> What I think is important is not to work directly with the PackageManifest but having an object manipulating it and able to answer to selectors like:
> MyPackage>>description
> MyPackage>>description: aText

We are doing the same thing then.

> I work on a spec widget to edit some package meta-data.
> Maybe you could do the same to be able to present other meta-data than the package comment from Nautilus. It is more work and can just come for a second version.

I think that will be necessary for sure.

For now, it seems really easy and straightforward to show comments in Nautilus.

It uses the same real state that class comments use.

Other metadata, I'm not sure how it would work.

That would fall more under the province of a PackageBrowser or something like that.

Dolphin has this problem solved in a nice way (I don't know how other Smalltalks solve it)

So, to clear thing up,

what are you saying?

1 - Don't mention putting other information in the default package comment

2 - Make more methods for other metadata such as [...]

3 - Both, 1 and 2

4 - Other?

demarey

Re: Default package comment

Le 18 mai 2015 à 15:17, Sergio Fedi a écrit :

> > > Personally, I do not fear to change the comment implementation later.
> > > That's what Smalltalk is good at.
> >
> > +1. But the most difficult thing is not to change the implementation but all its usage.
> > if people start to use a feature and you change the way to use it after, it is more difficult to update all users of the feature.
>
> Problem is, this feature is not used now because it doesn't exist.
>
> Bottom line is:
>
> If the future usage problem is about what to put in the default comment, It's ok for me to change it however we decide.
> If the future usage problem is about what other metadata we put con the Manifest then it is irrelevant for this issue.
>
> > > preInstallComment
> > > postInstallComment
> >
> > what is that? if it is Smalltalk code to run before/after the installation, it should not be in the comment but in a separated method.
> > Pharo misses a package setUp and tearDown methods.
>
> These are comments relating to thing you have to be aware of before installing and after installing the package.
> For example, a behaviour changed on some objects.

This example looks strange to me. It means you put some kind of changelog (or upgrade instructions) of your package in the package comments.
But you do not know from which version the user will upgrade. Will you keep all upgrade instructions?

> A new option on a menu. Another package that does not "get along" with this package.
>
> Things that are not code, but are relevant either before or after the loading of a package.

Maybe you do not need a specific part for such information because I think (hope) most packages will not require such kind of information.

>
> > > authorshipText
> > > contactDescription
> > > creationDate
> > > lastUpdateDate
> >
> > This information is meta-information on a package and should not be lost in the package comment.
>
> Exactly.
>
> Except that when you can't put it anywhere else, it usually ends up in the comment.
> (my argument is: as long as you don't have anywhere else to put certain info, it's better to have it somewhere rather than nowhere, so you could suggest that in the default comment)
>
> > > My initial strategy was to have comments and then model the commonalities of all package comments away to the appropiate method/variable/data
> >
> > I already started to work on some specific package meta-data.
> > As I wrote before, for now, I store it in the PackageManifest because Monticello does not have a good support for meta-data.
> > But anyway, we could just see that as an "implementation details".
> > What I think is important is not to work directly with the PackageManifest but having an object manipulating it and able to answer to selectors like:
> > MyPackage>>description
> > MyPackage>>description: aText
>
> We are doing the same thing then.
>
> > I work on a spec widget to edit some package meta-data.
> > Maybe you could do the same to be able to present other meta-data than the package comment from Nautilus. It is more work and can just come for a second version.
>
> I think that will be necessary for sure.
>
> For now, it seems really easy and straightforward to show comments in Nautilus.
> It uses the same real state that class comments use.
>
> Other metadata, I'm not sure how it would work.
> That would fall more under the province of a PackageBrowser or something like that.
> Dolphin has this problem solved in a nice way (I don't know how other Smalltalks solve it)

Could you describe me how Dolphin does and/or if you have some screenshots?

> So, to clear thing up,
> what are you saying?

2 - Make more methods for other metadata such as [...]

you may concatenate this information into the package comment for the display part even if not yet editable.

>
> 1 - Don't mention putting other information in the default package comment
> 2 - Make more methods for other metadata such as [...]
> 3 - Both, 1 and 2
> 4 - Other?

smime.p7s (5K) Download Attachment

Sergio Fedi

Re: Default package comment

> Things that are not code, but are relevant either before or after the loading of a package.

Maybe you do not need a specific part for such information because I think (hope) most packages will not require such kind of information.

Indeed I think we don't need a separate place to put this, because it's pretty rare.

> Dolphin has this problem solved in a nice way (I don't know how other Smalltalks solve it)

Could you describe me how Dolphin does and/or if you have some screenshots?

Sure, see below.

> So, to clear thing up,
> what are you saying?

2 - Make more methods for other metadata such as [...]

you may concatenate this information into the package comment for the display part even if not yet editable.

Cristal clear.

In this case, then the comment functionality we are adding should be followed with more work, adding more metadata in the Manifests (or refactoring Manifests)

Top left pane: File system tree where packages are located

Down left pane: Packages in the file system location selected above

Tabs:

Comment - Whatever text you put

Classes - Classes defined by the package

Loose methods - Methods in classes added by the package that are not in classes defined by the package

Resources - Objects embedded in the package (that is, serialized instances) Mainly used for window views.

Globals - Entries in the system dictionary that are defined by the package

Scripts - This tab has four subtabs: preinstall, postinstall, preuninstall, postuninstall

These scripts where ran in the appropriate stage of installing/uninstalling the package

Prerequisites - Depending on the classes, globals, etc, referenced by the classes and methods,etc from the package, the browser determined it's dependencies and this information would be then saved in the package itself. If the package had circular dependencies, then it wouldn't allow you to save it. The prerequisites listed you the packages which yoyr package depended on and why. That is, a list of which method referenced something outside the package.

Dependents - As prerequisites, but shows the packages that depend on your package, and why

Example of Dependents:

The second dependency is created because the method references a class:

agent

"Answers the IAgentCtl for the receiver's avatars"

agent isNull ifTrue: [

agent := IAgentCtlEx new.

agent connected: true ].

^agent

demarey

Re: Default package comment

Le 19 mai 2015 à 16:03, Sergio Fedi a écrit :

<DolphinPackageBrowser.png>

Top left pane: File system tree where packages are located
Down left pane: Packages in the file system location selected above

Tabs:
Comment - Whatever text you put
Classes - Classes defined by the package
Loose methods - Methods in classes added by the package that are not in classes defined by the package
Resources - Objects embedded in the package (that is, serialized instances) Mainly used for window views.
Globals - Entries in the system dictionary that are defined by the package
Scripts - This tab has four subtabs: preinstall, postinstall, preuninstall, postuninstall
These scripts where ran in the appropriate stage of installing/uninstalling the package
Prerequisites - Depending on the classes, globals, etc, referenced by the classes and methods,etc from the package, the browser determined it's dependencies and this information would be then saved in the package itself. If the package had circular dependencies, then it wouldn't allow you to save it. The prerequisites listed you the packages which yoyr package depended on and why. That is, a list of which method referenced something outside the package.
Dependents - As prerequisites, but shows the packages that depend on your package, and why

Example of Dependents:

<DolphinDependentsFeature.png>

The second dependency is created because the method references a class:

agent
"Answers the IAgentCtl for the receiver's avatars"

agent isNull ifTrue: [
agent := IAgentCtlEx new.
agent connected: true ].
^agent

thanks for the information.

smime.p7s (5K) Download Attachment