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?
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.
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 -- View this message in context: http://forum.world.st/Default-package-comment-tp4826400p4826523.html Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
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 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 -- View this message in context: http://forum.world.st/Default-package-comment-tp4826400p4826549.html Sent from the Pharo Smalltalk Developers mailing list archive at Nabble.com.
Hi Sergio, On Fri, May 15, 2015 at 6:28 AM, Sergio Fedi <sergio.fedi@gmail.com> 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
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.
On Fri, May 15, 2015 at 9:40 AM, Sergio Fedi <sergio.fedi@gmail.com> 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
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.
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
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?
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?
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 method*s - 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
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.
participants (4)
-
Christophe Demarey -
Eliot Miranda -
Sean P. DeNigris -
Sergio Fedi