I've taken it upon myself to write the article...I'm not the expert, but I thought I should give back. Can the experts please review it and get in touch with me privately regarding any corrections/suggestions?
You don't exactly have to worry about using CVS on the KB document, because editing the KB article itself, every change is recorded wikipedia style, with diffs.
Edit:
Note: I didn't actually proofread the article for inaccuracies. Merely cut and pasted, added formatting, links, etc.
Note2: You can't edit the KB article, only project moderators can do that.
As Xinhuan mentioned, your article is very long. Some specific suggestions:
"Their intended users are not specific to Mages, Healers, or Druids, etc." I've read through this paragraph a dozen times and still am not quite sure what this sentence is supposed to mean. In fact, I'd get rid of most of the whole introduction, and just start out with a simple sentence or two describing the purpose of the guide. I also don't think there's a need to explain that the guide isn't about how to write addons. If someone reads "This guide will walk you through the process of making your addon available on Curse." and still thinks the guide might tell them how to write an addon, well, they're probably a lost cause.
Don't delve into history. Nobody trying to figure out how to post their addon on Curse cares who wrote which VCS, why they wrote it, or which VCS the Mozilla project uses.
Keep things simple and to the point. Provide just the facts. Try to write enough that someone who doesn't have a background in software development can follow along, but not so much that someone who does know what version control is isn't hitting Page Down and trying to scan for the next section that actually tells them something about hosting addons on Curse.
I'd actually recommend removing a lot of your information, and instead providing links to existing KB articles on specific topics. A lot of the information in your article is already available. For example:
I understand the concerns about the history of things being "overkill", but I thought some might find it interesting, so I included it. I also included a statement saying it's not mandatory to read that section.
As for removing sections that are covered by other KB articles, I disagree...
The whole reason for the article was to explain everything from point A to point Z. This way, someone trying to learn all of what I learned through the posts, KB articles, etc., won't have to go scouring the website trying to fit the puzzle pieces together. I found that the information in existing KB articles left out information (puzzle pieces) that forum messages eventually filled in. The intent was to take all of that information and put it together in ONE place and spell it out for the reader. It was like buying a piece of furniture you have to assemble, but only getting steps 1, 3, 6, and 8 in the assmebly instructions included in the box; the rest of the instructions you had to find from some place online.
So, it may seem redundant to include the informaton already contained in some the KBs, but the intent was to fill in, elaborate, and spell it out...
Note2: You can't edit the KB article, only project moderators can do that.
Does this mean I won't be able to gain access to make revisions here on CurseForge? I would be more than happy to make some of the changes you suggest, and I should be the one to correct it since it is my article.
Their intended users are not specific to Mages, Healers, or Druids, etc."
The sentence is attempting to provide an example of what a small scale addon might be; addons specific to Mages (class), Healers (functions in raids, like tanks, dps, etc), druids (misprint--intended to read "Blood Elf" as example for race, same reason as the other two). Essentially, targeted addons can/usually are small, while addons like Auctioneer, Bartender, Pitbull, etc., are meant for all characters, races, and functions in raids, and are usually very large and complex.
Does this mean I won't be able to gain access to make revisions here on CurseForge? I would be more than happy to make some of the changes you suggest, and I should be the one to correct it since it is my article.
I'm not sure if the wowace/curseforge system even allows non-moderators to have access to modifying KB articles. Maybe an admin would know.
So, it may seem redundant to include the informaton already contained in some the KBs, but the intent was to fill in, elaborate, and spell it out...
Which is why I suggested improving the existing articles. What's the point in having one article that explains something, and another article that explains something in more detail? There's no reason to have both. For example, Getting Started with Project Management has pretty much the same purpose as your article.
Also, having multiple articles that link to each other is preferrable... that way, someone who just wants to know about the different version control systems CurseForge offers doesn't have to read through a novel to find the few relevant paragraphs. Modern browsers have all kinds of nifty features like new tabs and back buttons that make it easy to browse multiple pages.
Essentially, targeted addons can/usually are small, while addons like Auctioneer, Bartender, Pitbull, etc., are meant for all characters, races, and functions in raids, and are usually very large and complex.
I'd advise against making generalizations like this. I can think of dozens of addons whose functionality is totally independent of class, role, or race, but are very small and simple. Likewise, there are many class-specific or role-specific addons that are anything but simpleNecrosis comes to mind, as does PallyPower. Additionally, the choice to use version control isn't necessarily dependent on an addon's complexity. I use it for my addon Unlinked, which is 150 lines of code including the options. Other authors may choose not to use version control, or may have their own VCS independent of CurseForge/WowAce.
Well, assuming I can get author status (or whatever you want to call it) and am able to edit what is now in the KB, I'll make revisions.
I maintain that the three main reasons for the article (improving upon existing articles by elaborating, bringing them into one place as much as possible, and placing steps into chronological order) are valid enough. The argument of just improving the existing ones is also valid (since that was one of the intended purposes of my article). It really is a matter of preference. Some people might prefer having everything in one place, while others, like Phanx, don't mind browsing through multiple short, pointed articles and sifting through forum posts. I personally found them a bit cryptic. No offense intended.
What it boils down to is: A matter of preference. With the existing articles and mine both in the KB, it may seem redundant to some, but we have catered to both styles of learning. (No one person learns exactly the same.)
I don't normally mix personal life into forum posts, but I'll have to make an exception here... I've got a baby due in 5 days so if I'm going to make any changes, it'll have to be very soon or as soon as I can after baby is here...
Hey guys - I realize this is an old thread, so I hope this is the most appropriate place for my question. I've read this thread (as well as many others), all the FAQs, etc. There is one point on which I haven't really seen a solid answer (or if there was, I didn't realize that it was referring to the subject in question).
When adding a new library to "default relationships", you have 4 options for "Type" - Required Dependency, Optional Dependency, Embedded Library, and Tool Used. The only thing I'm a little unclear on is when I should choose "Optional Dependency" vs. "Embedded Library".
In most of the documents, posts, and other information I've been able to find on the subject, the two terms seem to be used interchangeably. In fact, I think almost everything I've read says something along the lines of (or even exactly like) "If you are embedding a library, you should specify it as an optional dependency in your .pkgmeta file". Hmm, ok, that's cleared up....but what about this dropdown on the "Default Relationships" tab of project management? (Did someone put both of those in there as a prank to confuse us? :P)
Thanks in advance!
BTW, I tried searching the forums for 'default relationships', but no matter what I do, it always gives me an error:
"Your submission could not be processed because a security token was missing."
Now, based on the stuff he's written in the description, I infer that the "Embedded Library" option is something like an optional dependency that will still be included in the nolib package....? Is this guess anywhere in the neighborhood of correct? :D
P.S. It would be killer if the "Default Relationships" page of project management had a short blurb at the bottom describing what each option is (or more likely, a link to another page having that info). Ya know, sort of like a tooltip....
if your using the wowace side of the site, then there really should be no reason to be editing that information manually as that is auto populated by the .pkgmeta file.
The difference between embedded and optional lib is that embedded libs are just that. They appear with the addon in it's zip file and the user dosn't have to go looking for it. An optional dependancy is a feature that you have coded for, but is not a required aspect of the addon for the end user.
Due to the way WoW handles addons, it is the standard method to include your libs as optional dependancys because a user may choose to use those libs in standalone mode and your addons -nolib zip.
However this is a relatively advanced setup that most authors don't specifically account for, it's called a disembedded setup.
Short Answer: Don't edit the default relationships in the project management, just use .pkgmeta and let it do it's magic
"Embedded Library" = The addon will be added to your addon as if it were part of your addon and is required to be either embedded or installed separately and your addon will not work without it.
"Optional Dependency" = The addon page will link to said addon to give the user a convenient link to click and your addon will work without it.
Default relationships have nothing to do with your ToC and everything to do with how the Curse Client handles the package. This is how it works:
Require Dependency: Curse Client will download.
Optional Dependency: Curse Client will not download, but users will see this as an optional package that adds features to yours.
Embedded Library: Curse Client will download.
Tools used: Curse Client will not download (It's more than likely embedded in the repository)
In all cases except for Optional Dependency, the other project will be eligible for Reward Points. This is why managers of manually-uploaded projects should be courteous and take the time to edit default relationships. If you're using a library, give credit.
if your using the wowace side of the site, then there really should be no reason to be editing that information manually as that is auto populated by the .pkgmeta file.
The difference between embedded and optional lib is that embedded libs are just that. They appear with the addon in it's zip file and the user dosn't have to go looking for it. An optional dependancy is a feature that you have coded for, but is not a required aspect of the addon for the end user.
Due to the way WoW handles addons, it is the standard method to include your libs as optional dependancys because a user may choose to use those libs in standalone mode and your addons -nolib zip.
However this is a relatively advanced setup that most authors don't specifically account for, it's called a disembedded setup.
Short Answer: Don't edit the default relationships in the project management, just use .pkgmeta and let it do it's magic
Thanks for the reply. I should have provided a bit more background, I suppose. I have been working in game development for 7 years now, so I'm quite familiar with the _concepts_ of libs, dependencies, source control systems, packaging without libraries, creating redist packages, etc. etc......but I've never worked with YAML or SVN.
I can also understand that the .pkgmeta file is the essential file for telling the packager what to do....as I said, I did actually read the dozens of pages containing information about the process, before I posted :)
I believe the most confusing thing for me was that a lot of the documentation and forum posts on the subject seem to use "optional dependencies" and "embedded libraries" interchangeably or ambiguously (i.e. using one term but meaning the other). In fact, most of the information I've seen mentions embedding libraries, but also make sure to mark them as optional dependencies (see the forum threads linked from the 'Packaging an Addon' FAQ).
In addition, the word "embed" isn't used anywhere on the pkgmeta FAQ - in fact the only place I was able to find that tied pkgmeta externals to embedding libraries was a small paragraph on the "Packaging an Addon" page (the paragraph under the "Use of Libraries" header).
Anyway - I'm now on my third WoW addon, but I wasn't able to get the first one to package properly until I stumbled across the Default Relationships page and set my dependencies there. It's very likely that the true culprit was my limited understanding of how the .pkgmeta was configured, but since then...I've always just set dependencies in both places. So far, I've been embedding everything, since this is the only way I method I feel that I know enough about to ensure an error-free installation for the end user, based on my knowledge of the process.
However, I would like to package my addons in whatever manner makes it easiest for the user to install and update, while consuming the least amount of redundant system resources. I thought it was time I got it clear in my head exactly when I need to be using which method.
Default relationships have nothing to do with your ToC and everything to do with how the Curse Client handles the package. This is how it works:
Require Dependency: Curse Client will download.
Optional Dependency: Curse Client will not download, but users will see this as an optional package that adds features to yours.
Embedded Library: Curse Client will download.
Tools used: Curse Client will not download (It's more than likely embedded in the repository)
In all cases except for Optional Dependency, the other project will be eligible for Reward Points. This is why managers of manually-uploaded projects should be courteous and take the time to edit default relationships. If you're using a library, give credit.
Thanks a lot! That is precisely the info I was looking for. Humm, just to clarify something you mentioned, regarding Curse client. Is editing the Default Relationships [via the web portal] something that is required for the Curse client, in addition to specifying dependencies via the pkgmeta file? Or, does the pkgmeta data get applied to the same bin as the Default Relationships form? In other words, are the pkgmeta and the Default Relationships form two different interfaces for changing the same data (which is how I understand it to work), or does the Curse client rely solely on the data entered via the default relationships page?
If you're using a .pkgmeta file, the Default Relationships are automatically filled in. You don't need to go edit them through the web interface, though you may want to check to make sure you've gotten it right in your .pkgmeta.
You only need to edit the Default Relationships through the web interface if you're not using a CurseForge/WowAce repository, and manually upload files for your addon.
Ok so I've almost given up -0 there is no list of what you have to do to upload a change to an addon
I've done the easy bits - I've got the owner to add me
I've found the bits where the WOW API changed and fixed them
I've debugged it - got it working
I've change the version number in the TOC file
I've zipped the whole directory up
I've uploaded it to CurseForge - I even gave the upload a version number which matched the filename of the ZIP file and the version number in the TOC
Is that all I have to do - and I just wait?
Now what?
A few extra comments I ignored all the SVN/GIT stuff - (I have TortiseSVN installed as I use it for other stuff) but to try and keep this CurseForge update simple I've ignored that for the moment.
I've cruised around every FAQ and forum I can find and I still don't know if I've done all thats needed.
Rollback Post to RevisionRollBack
To post a comment, please login or register a new account.
Anyway...I'll setup a Google project for it....In the mean time, turn on your YahooIM...
-
View User Profile
-
View Posts
-
Send Message
Curse PremiumHmmm, that PDF is somewhat "longish" for a KB article.
Still, I have reproduced the entire article here:
http://kb.wowace.com/projects/packaging-an-addon-for-curse/
You don't exactly have to worry about using CVS on the KB document, because editing the KB article itself, every change is recorded wikipedia style, with diffs.
Edit:
Note: I didn't actually proofread the article for inaccuracies. Merely cut and pasted, added formatting, links, etc.
Note2: You can't edit the KB article, only project moderators can do that.
"Their intended users are not specific to Mages, Healers, or Druids, etc." I've read through this paragraph a dozen times and still am not quite sure what this sentence is supposed to mean. In fact, I'd get rid of most of the whole introduction, and just start out with a simple sentence or two describing the purpose of the guide. I also don't think there's a need to explain that the guide isn't about how to write addons. If someone reads "This guide will walk you through the process of making your addon available on Curse." and still thinks the guide might tell them how to write an addon, well, they're probably a lost cause.
Don't delve into history. Nobody trying to figure out how to post their addon on Curse cares who wrote which VCS, why they wrote it, or which VCS the Mozilla project uses.
Keep things simple and to the point. Provide just the facts. Try to write enough that someone who doesn't have a background in software development can follow along, but not so much that someone who does know what version control is isn't hitting Page Down and trying to scan for the next section that actually tells them something about hosting addons on Curse.
I'd actually recommend removing a lot of your information, and instead providing links to existing KB articles on specific topics. A lot of the information in your article is already available. For example:
- Getting started with Project Management
- What to do after creating a project
- Why use Revision Control?
- Repository FAQ
Rather than writing a new article, you might consider improving some of the existing articles.As for removing sections that are covered by other KB articles, I disagree...
The whole reason for the article was to explain everything from point A to point Z. This way, someone trying to learn all of what I learned through the posts, KB articles, etc., won't have to go scouring the website trying to fit the puzzle pieces together. I found that the information in existing KB articles left out information (puzzle pieces) that forum messages eventually filled in. The intent was to take all of that information and put it together in ONE place and spell it out for the reader. It was like buying a piece of furniture you have to assemble, but only getting steps 1, 3, 6, and 8 in the assmebly instructions included in the box; the rest of the instructions you had to find from some place online.
So, it may seem redundant to include the informaton already contained in some the KBs, but the intent was to fill in, elaborate, and spell it out...
Does this mean I won't be able to gain access to make revisions here on CurseForge? I would be more than happy to make some of the changes you suggest, and I should be the one to correct it since it is my article.
The sentence is attempting to provide an example of what a small scale addon might be; addons specific to Mages (class), Healers (functions in raids, like tanks, dps, etc), druids (misprint--intended to read "Blood Elf" as example for race, same reason as the other two). Essentially, targeted addons can/usually are small, while addons like Auctioneer, Bartender, Pitbull, etc., are meant for all characters, races, and functions in raids, and are usually very large and complex.
-
View User Profile
-
View Posts
-
Send Message
Curse PremiumI'm not sure if the wowace/curseforge system even allows non-moderators to have access to modifying KB articles. Maybe an admin would know.
Google exists for a reason. :p
Which is why I suggested improving the existing articles. What's the point in having one article that explains something, and another article that explains something in more detail? There's no reason to have both. For example, Getting Started with Project Management has pretty much the same purpose as your article.
Also, having multiple articles that link to each other is preferrable... that way, someone who just wants to know about the different version control systems CurseForge offers doesn't have to read through a novel to find the few relevant paragraphs. Modern browsers have all kinds of nifty features like new tabs and back buttons that make it easy to browse multiple pages.
I'd advise against making generalizations like this. I can think of dozens of addons whose functionality is totally independent of class, role, or race, but are very small and simple. Likewise, there are many class-specific or role-specific addons that are anything but simpleNecrosis comes to mind, as does PallyPower. Additionally, the choice to use version control isn't necessarily dependent on an addon's complexity. I use it for my addon Unlinked, which is 150 lines of code including the options. Other authors may choose not to use version control, or may have their own VCS independent of CurseForge/WowAce.
I maintain that the three main reasons for the article (improving upon existing articles by elaborating, bringing them into one place as much as possible, and placing steps into chronological order) are valid enough. The argument of just improving the existing ones is also valid (since that was one of the intended purposes of my article). It really is a matter of preference. Some people might prefer having everything in one place, while others, like Phanx, don't mind browsing through multiple short, pointed articles and sifting through forum posts. I personally found them a bit cryptic. No offense intended.
What it boils down to is: A matter of preference. With the existing articles and mine both in the KB, it may seem redundant to some, but we have catered to both styles of learning. (No one person learns exactly the same.)
I don't normally mix personal life into forum posts, but I'll have to make an exception here... I've got a baby due in 5 days so if I'm going to make any changes, it'll have to be very soon or as soon as I can after baby is here...
-
View User Profile
-
View Posts
-
Send Message
Curse Premiumhttp://kb.curseforge.com/projects/packaging-an-addon-for-curse/
I wonder why they didn't sync, so I created a copy on Curseforge for now.
When adding a new library to "default relationships", you have 4 options for "Type" - Required Dependency, Optional Dependency, Embedded Library, and Tool Used. The only thing I'm a little unclear on is when I should choose "Optional Dependency" vs. "Embedded Library".
In most of the documents, posts, and other information I've been able to find on the subject, the two terms seem to be used interchangeably. In fact, I think almost everything I've read says something along the lines of (or even exactly like) "If you are embedding a library, you should specify it as an optional dependency in your .pkgmeta file". Hmm, ok, that's cleared up....but what about this dropdown on the "Default Relationships" tab of project management? (Did someone put both of those in there as a prank to confuse us? :P)
Thanks in advance!
BTW, I tried searching the forums for 'default relationships', but no matter what I do, it always gives me an error:
"Your submission could not be processed because a security token was missing."
I then googled it, and after a few tries was able to get a result related to this matter, from this page:
http://wow.curse.com/downloads/wow-addons/details/libdatabroker-1-1.aspx
Now, based on the stuff he's written in the description, I infer that the "Embedded Library" option is something like an optional dependency that will still be included in the nolib package....? Is this guess anywhere in the neighborhood of correct? :D
-
View User Profile
-
View Posts
-
Send Message
Curse PremiumThe difference between embedded and optional lib is that embedded libs are just that. They appear with the addon in it's zip file and the user dosn't have to go looking for it. An optional dependancy is a feature that you have coded for, but is not a required aspect of the addon for the end user.
Due to the way WoW handles addons, it is the standard method to include your libs as optional dependancys because a user may choose to use those libs in standalone mode and your addons -nolib zip.
However this is a relatively advanced setup that most authors don't specifically account for, it's called a disembedded setup.
Short Answer: Don't edit the default relationships in the project management, just use .pkgmeta and let it do it's magic
"Optional Dependency" = The addon page will link to said addon to give the user a convenient link to click and your addon will work without it.
That's my take on it, anyway.
-
View User Profile
-
View Posts
-
Send Message
Project AuthorRequire Dependency: Curse Client will download.
Optional Dependency: Curse Client will not download, but users will see this as an optional package that adds features to yours.
Embedded Library: Curse Client will download.
Tools used: Curse Client will not download (It's more than likely embedded in the repository)
In all cases except for Optional Dependency, the other project will be eligible for Reward Points. This is why managers of manually-uploaded projects should be courteous and take the time to edit default relationships. If you're using a library, give credit.
Thanks for the reply. I should have provided a bit more background, I suppose. I have been working in game development for 7 years now, so I'm quite familiar with the _concepts_ of libs, dependencies, source control systems, packaging without libraries, creating redist packages, etc. etc......but I've never worked with YAML or SVN.
I can also understand that the .pkgmeta file is the essential file for telling the packager what to do....as I said, I did actually read the dozens of pages containing information about the process, before I posted :)
I believe the most confusing thing for me was that a lot of the documentation and forum posts on the subject seem to use "optional dependencies" and "embedded libraries" interchangeably or ambiguously (i.e. using one term but meaning the other). In fact, most of the information I've seen mentions embedding libraries, but also make sure to mark them as optional dependencies (see the forum threads linked from the 'Packaging an Addon' FAQ).
In addition, the word "embed" isn't used anywhere on the pkgmeta FAQ - in fact the only place I was able to find that tied pkgmeta externals to embedding libraries was a small paragraph on the "Packaging an Addon" page (the paragraph under the "Use of Libraries" header).
Anyway - I'm now on my third WoW addon, but I wasn't able to get the first one to package properly until I stumbled across the Default Relationships page and set my dependencies there. It's very likely that the true culprit was my limited understanding of how the .pkgmeta was configured, but since then...I've always just set dependencies in both places. So far, I've been embedding everything, since this is the only way I method I feel that I know enough about to ensure an error-free installation for the end user, based on my knowledge of the process.
However, I would like to package my addons in whatever manner makes it easiest for the user to install and update, while consuming the least amount of redundant system resources. I thought it was time I got it clear in my head exactly when I need to be using which method.
Thanks a lot! That is precisely the info I was looking for. Humm, just to clarify something you mentioned, regarding Curse client. Is editing the Default Relationships [via the web portal] something that is required for the Curse client, in addition to specifying dependencies via the pkgmeta file? Or, does the pkgmeta data get applied to the same bin as the Default Relationships form? In other words, are the pkgmeta and the Default Relationships form two different interfaces for changing the same data (which is how I understand it to work), or does the Curse client rely solely on the data entered via the default relationships page?
You only need to edit the Default Relationships through the web interface if you're not using a CurseForge/WowAce repository, and manually upload files for your addon.
I've done the easy bits - I've got the owner to add me
I've found the bits where the WOW API changed and fixed them
I've debugged it - got it working
I've change the version number in the TOC file
I've zipped the whole directory up
I've uploaded it to CurseForge - I even gave the upload a version number which matched the filename of the ZIP file and the version number in the TOC
Is that all I have to do - and I just wait?
Now what?
A few extra comments I ignored all the SVN/GIT stuff - (I have TortiseSVN installed as I use it for other stuff) but to try and keep this CurseForge update simple I've ignored that for the moment.
I've cruised around every FAQ and forum I can find and I still don't know if I've done all thats needed.