ElkArte Community

Extending Elk => Addons => Topic started by: Spuds on December 20, 2014, 10:36:14 pm

Title: How to add your addon to the Addon site listing
Post by: Spuds on December 20, 2014, 10:36:14 pm
Introduction
You finished your addon and now want to add it to the addon site, great!

To do so you need to make a PR to the elkarte/addons repo (https://github.com/elkarte/addons/) in the gh-pages branch (https://github.com/elkarte/addons/tree/gh-pages).  The how to fork a repo, make a local copy, apply your changes, and submit the PR are not part of this guide. There are many guides on how to do this and it all depends on what tools you have chosen. This help text assumes you know how to make a PR.

To add your addon to the listing, you need to commit just a single file under the _posts directory. The file must follow the naming convention of YYYY-MM-DD-Addon Name The date should be the intial release date of your addon, that date is only used to create the permalink to the file.

The above file must contain the following sections (see any of the existing files in the _posts directory for examples)
Code: [Select]
---
front matter
---

detailed description

Front Matter
The front matter is what makes everything cool happen. The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines. Meaning the information contained between the --- & --- tags is in YAML format and is specially processed by Jekyll.
Don't want to learn YAML?, good neither did I and you don't have either, just follow along.

Example front matter
Code: [Select]
---
layout: post
title: "Title of addon"
category: name
date: YYYY-MM-DD
comments: false
short: "A short description of the addon"
license: license
version: x.x.x
allhooks: boolean
elkversion: 1.0
support: valid link or null
bugs: valid link or null
author: thats you
thumbnail: valid link or null
download: valid link
images:
  - Some name: link to it
  - Another name: link to it
---

Markdown text

## Installation:
{% include install_std.MD %}

## License:
{% include license.MD param="BSD" %}
Front Matter Details

Two helper templates are provided, one is the generic addon installation instructions and the other is the license block. To use the installation template add
[/list]
Code: [Select]
## Installation:
{% include install_std.MD %}

For the license template use the following with a param of
Code: [Select]
### License:
{% include license.MD param="MPL 1.1" %}
Title: Re: How to add your addon to the Addon site listing
Post by: ahrasis on December 21, 2014, 05:05:21 am
Thanks you for the guide. If we create it in the github, where do we make its PR?
Title: Re: How to add your addon to the Addon site listing
Post by: emanuele on December 21, 2014, 10:21:42 am
Great! Thanks!

/me marks unread in order to remember reading it
Title: Re: How to add your addon to the Addon site listing
Post by: emanuele on December 23, 2014, 05:50:30 pm
A couple of small additions here too:
* the repository is https://github.com/elkarte/addons/
* the files should be added to the gh-pages branch https://github.com/elkarte/addons/tree/gh-pages
O:-)
Title: Re: How to add your addon to the Addon site listing
Post by: Joshua Dickerson on December 23, 2014, 05:57:43 pm
@Spuds, would it be possible to do this with a form on this site?
Title: Re: How to add your addon to the Addon site listing
Post by: Spuds on December 23, 2014, 06:03:32 pm
Good point, updated the original a bit with the specific branch info.

@Spuds, would it be possible to do this with a form on this site?
I'd venture to say yes, and that would be pretty cool!   The information needed is not that much, so easy to collect with a form.   Then we should be able to use the api to send a PR to the branch.  Never looked in to the api though.
Title: Re: How to add your addon to the Addon site listing
Post by: emanuele on December 23, 2014, 06:07:28 pm
I think it is not trivial, mainly because you have to create a commit and then a pull request...
Title: Re: How to add your addon to the Addon site listing
Post by: Joshua Dickerson on December 23, 2014, 06:20:01 pm
Hmm... I think you're right @emanuele. I just did a quick look at the Github API and I don't see anything for making a commit or PR.
Title: Re: How to add your addon to the Addon site listing
Post by: emanuele on December 23, 2014, 06:49:46 pm
Yep, I quickly looked into it about a year ago for the languages repo (my idea was to let users submit translations directly from the admin panel), but the only solutions I came up with was to have to "create" the commit via php, push the branch and make the pr (https://developer.github.com/v3/pulls/#create-a-pull-request).
Title: Re: How to add your addon to the Addon site listing
Post by: Burke Knight on June 18, 2015, 07:16:58 am
Hmm... Upon my first try, I got this email sent to me by GitHub:

Quote
The page build completed successfully, but returned the following warning:

CNAME already taken: addons.elkarte.net

For information on troubleshooting Jekyll see:

  https://help.github.com/articles/using-jekyll-with-pages#troubleshooting

If you have any questions you can contact us by replying to this email.

I'll wait for reply, before I do any more. (Will give me chance to get rest fully done first, instead of on the go working...LOL)
Title: Re: How to add your addon to the Addon site listing
Post by: emanuele on June 18, 2015, 11:07:26 am
No idea... lol
One thing that may be broken is also:
Code: [Select]
bugs: valid link or null
I'm not sure if you should just remove it?
Spuds for sure knows moar! :P
Title: Re: How to add your addon to the Addon site listing
Post by: Burke Knight on June 18, 2015, 01:47:58 pm
No idea... lol
One thing that may be broken is also:
Code: [Select]
bugs: valid link or null
I'm not sure if you should just remove it?
Spuds for sure knows moar! :P


Um... I think I need to edit it, then, because I missed that.
Meant to add the link to the GitHub Issues for the Repo for it.  :-[
Hey, what can I say? Look at the time I did it.... LOL

EDIT: Just updated it, and still got the email. Strange... LOL
Title: Re: How to add your addon to the Addon site listing
Post by: Spuds on June 19, 2015, 03:35:44 pm
The CNAME error is an annoyance, and it comes from your own fork, really its kind of a GitHub error. 

So the "error" is because once you forked the addons gh-pages repo you now have the CNAME file in your fork.  However the CNAME (part of the repo of course like any other file) is "taken" already, so you get an error when making PR's even though you are not submitting the CNAME file.

I suspect you can delete/rename the CNAME in your fork or change your forked branch name from gh-pages to something else, like bks_addons and then make your PR's from that branch to the addons gh-pages repo.  This is one of those fun with git things that can annoy the crap out of the best of us.
Title: Re: How to add your addon to the Addon site listing
Post by: vbgamer45 on January 27, 2017, 05:06:54 pm
Can the download link be set to a page or dynamic link?
I have setup a downloads system with a public download link. Example page http://www.elkartemods.com/index.php?action=downloads;sa=view;down=2  And then the direct link http://www.elkartemods.com/index.php?action=downloads;sa=downfile&id=2

Would allow me to keep files updated a little easier.
Title: Re: How to add your addon to the Addon site listing
Post by: emanuele on January 27, 2017, 08:01:15 pm
If I read it correctly, you just set the "download" parameter to a valid URL and it should pick it. ;)
Title: Re: How to add your addon to the Addon site listing
Post by: vbgamer45 on January 27, 2017, 08:25:01 pm
So this would work ok: http://www.elkartemods.com/index.php?action=downloads;sa=downfile&id=2
Title: Re: How to add your addon to the Addon site listing
Post by: inter on December 01, 2017, 10:20:51 am
idea: on http://addons.elkarte.net/ need to add a link to the top of the page: "how create addon"
Title: Re: How to add your addon to the Addon site listing
Post by: Spuds on December 01, 2017, 02:24:40 pm
You mean a help button back to this thread or maybe a page on the addon site ?
Title: Re: How to add your addon to the Addon site listing
Post by: inter on December 01, 2017, 04:32:28 pm
This link would be useful for beginners. This is a link to a page or forum topic with instructions or a group of links to various instructions and real examples. Something like that.