Idea for Attribution / Release Notes / Version Standard Form

@DanThomas and I have been discussing this in other topics.
I just had an idea I want to share with everyone, and get your feedback.

First, rather than calling this "Attribution", I propose to call it "ReleaseNotes" which includes the attribution info. "Attribution" is too limited a term, IMO.

So, I have this draft form, that uses a KM Action "Set Variable" instead of a "Comment" Action:

I like the "Set Variable" action because it makes that information available ( in the KM Variable "ReleaseNotes") to other Actions and sub-macros to use or display if needed.

As Dan and I have discussed, putting the version into in the "name" of the Action makes it more unlikely to be changed (accidentally or otherwise) by users who download the macro.

If we use a standard format for this name, and Macro Master Dan can figure out how to read the Action Name from script, then I think we have a good approach.

Your thoughts?

I like the idea, but I’m not thrilled with using “Set Variable”. This is exactly what Comments are for, IMO.

“Release Notes” is a good name, but I’m not that concerned with what we call it. I can use regexes to determine if something has version info in the Name.

I agree, in general. But I just had this case where I wanted to display the ReleaseNotes to the user. If these are in a Comment, then I have to duplicate them in a Set Variable or Display Text action. Unless you have some other idea?

Not really. In that case, I'd consider still using a comment with the version in the name, but the rest of it could say "see the "Set Variable" below for more information", or something like that.

How's that sound?

What is the advantage of using a Comment vs Set Variable for this purpose?

I don’t want to use Variables for this purpose as a standard. That’s not what they’re for.

If you want to do it on an individual basis, well, they’re more “guidelines” than “rules”, so that’s cool.

And if I write code to parse for version information, I suppose I could look in Set Variable actions also.

But I’m strongly opposed to use Set Variable for documentation. There’s this thing called “code smell”. And no, I’m not saying you smell, or your ideas smell. It’s a term programmers use for things that just don’t feel right. And this is one of those things that just has a “smell” to it, to me.

Of course, you’ve changed my mind before, so who knows, but that’s how I feel right now.

That's a new term for me. But I get your point -- it just doesn't feel right.

However, in my experience, putting program information in variables is hardly new. I'm using "variable" here in the broadest sense to include properties, resources, support files, etc, that at some point the software may need to display to the user.

There are some very common use cases on the Mac:

  1. File > Get Info
  2. App > About
  3. App > Release Notes
  4. Help > lots of stuff

I've been using AppleScript script properties for this purpose for a long time:

property ptyScriptName : "Locate Resources PKG"
property ptyScriptVer : "1.0.1"
property ptyScriptDate : "2016-08-14"
property ptyScriptAuthor : "JMichaelTX"

Since these are at the top of the script, they serve the purpose of internal header comments. But then, if an error occurs, I can display these properties to help the user clearly identify where the error came from.
In fact, AppleScript has a built-in property called "version", which I should really set. Other scripts can get the version of another script without opening that script.

Don't most Windows apps have a similar approach?

So, my thought is that sometimes we might want to display Release Notes to the user. If we don't put that in a variable, how would we do it?

How about if we say that we should use a Comment, unless it becomes necessary to display the info. In that case, convert it to a variable.

Code Smell

Although from Wikipedia’s point of view, it seems it’s a little stronger term than I meant with regards to what you’re proposing.

IMO, that just complicates things. I don't see any advantages, and several disadvantages.

Since we seem to have different thoughts on this, why don't we give it a break for a day or two. There's no rush to move on this.

Good idea. By the way, I have no emotion invested in this. So it's cool we disagree. Well, not cool per se, but you know what I mean. :slight_smile:

Sorry, one other related thought struck me just after I posted that.

In another topic, we were discussing using a disabled “Display Text” so we could use rich text in the Release Notes and/or documentation.

I did/do like that idea as well. So that presents another option for Release Notes:

  • Comments
  • Set Variable
  • Display Text

I know, I’m going in the wrong direction. But perhaps it’s better to get all of the options on the table before making a decision.

Dang. I knew you were going to bring that up. :slight_smile:

Noted. I’ll cogitate on this for a while.

OK, time to re-address this.

Can we assume that the version information has to be in the first Action in a macro?

That would make it much easier for an automated process to “grab” the version information.

Yep. That's what I always do. Actually in the name of the Action. Using your script has worked fine.

OK, cool. Thanks.

I hope I’m close to releasing my first version of an installer - been working on it for weeks. I say “hope” because I keep thinking of little tweaks to make it work better. Like version checking, LOL.

Most macros won’t need an installer. But for macros that have Resources, and certain kinds of updated macros, I think it will be helpful. We’ll see.

IMO, all Macros uploaded should have ReleaseNotes as the first Action (whether it be a Comment, Display, or Set Variable Action).

My Macro to upload Macros is working very well now, and it provides for getting the ReleaseNotes and Version # and date.

For ref:

I have a new, improved version I'm testing now. Should be ready to upload within a day or so.

I was wondering something.

When using Chrome, if I want to include an image in a post, I just paste it into the post.

But Safari doesn’t support this, right? So that means people who want to include an image have to save it to disk first.

But in the KM Editor, the Edit->Copy As->Copy as Image only copies it to the clipboard. So how do people who use Safari use the copied image?

If all my prior assumptions are correct, then it would seem to me that creating a macro to automate this might be incredibly useful. Sounds like you’re the man for the job! :slight_smile:

Actually, I think @peternlewis built such a macro, maybe a year ago or so.
I'll have to check/search, see what I can find.

1 Like

Yep, here it is:

I've never used it since I almost always use Chrome.

2 Likes