Contribution convention

From WHMCS Documentation

So, you want to release and document your WHMCS module/modification/enhancement/template on the wiki? Follow these guidelines to get up and running and thank you for sharing!

Confused about something on this page? Not sure what to do? Ask on the talk page.

[edit] Naming your page

Your new page should be named accordingly: Contribution:ModificationName

I.E. If you're the creator of 'MyAwesomeModule', head along: Contribution:MyAwesomeModule!

[edit] Page content

Once you're there place the following on your new page:

{{Contribution|
| name = MyAwesomeModule
| author = Your name / wiki username
| admin = yes
| user = yes
| theme = yes
| desc = A short summary of your project
| version = Current version number
| zip = http://mydomain/link/to/download.zip
| targz = http://mydomain/link/to/download.tar.gz
}}

This calls the contribution template with various options, meaning your new page will be automatically formatted and added to the appropriate categories.

[edit] Parameter editing and explanation

{{Contribution|

This line should be left as it is - this is the name of the template being called.

| name = MyAwesomeModule

Your module's name

| author = Your name / wiki username

Take credit for your work! If you are registered on the wiki use your username - it will then automatically link to your userpage. Contributions will be automatically added to the category Category:Contributions/Authorname (which will also be linked to on the contribution's page).

| admin = yes
| user = yes
| theme = yes

These specify the type of modification. Admin-side, user-side or a new theme/template. Remove all those that don't apply to your contribution. Your page will be automatically categorised based upon these lines.

| desc = A short summary of your project

Let people know exactly what your modification does. Don't go mad, you can add a features section later, this should just be a short intro.

| version = Current version number

1.0 is always a good starting place.

| zip = http://mydomain/link/to/download.zip
| targz = http://mydomain/link/to/download.tar.gz

Specify the URL to download your modification from as either a .tar.gz or .zip file. You may use both formats, or either (See Optional parameters below if you don't want to use downloads). If your download is neither format or you want to link to a different page, use 'link' and 'linkname' instead:

| link = http://link/to/another/site/
| linkname = Download here

[edit] Optional parameters

| nofeatures = yes

Add this if you don't want to display a list of features. E.G. Matt's Banned Emails addon.

| nochangelog = yes

Add this if you don't want to maintain a project changelog. E.G. Matt's Banned Emails addon.

| code = yes

Add this to display the necessary code changes to make to install this contribution instead of showing download links. Code changes are stored in sub-pages (see below).

Note: If you supply download links they will be squashed by this option

[edit] After creation

After you click save you'll be presented with your contribution's page. As the description option above should only be a short introduction you can create a features sub-page for listing all that your contribution has to offer which will be automatically included in the appropriate place on the module page. A second sub-page can also be used to maintain a changelog. A link to both of these sub-pages are automatically included on your contribution's page, this link will disappear to be replaced with the page's content when the page exists.

A third sub-page can be created to display code changes to make instead of linking to installation files, though this will only be automatically included if the Contribution template is called with the code parameter set to 'yes'.

The sub-page names take the form of:

• Contribution:MyAwesomeModule/Features
• Contribution:MyAwesomeModule/Changelog
• Contribution:MyAwesomeModule/Code

[edit] Creating the changelog

1. Click the link placed on your contribution's page to create your changelog page - you'll be brought to a new page edit screen.
2. To create your first version header use {{CL version|1.0}}, where 1.0 is your starting version number.
3. Add your first (or only, this is the first release after all!) item with: {{CL item|type|Description}} - 'type' should be one of the following:
   • new
   • fix
   • change
   • update

[edit] Creating the features page

Simply follow the link provided on your contribution's page to create the features sub-page and write your list of features there. Preferably each item should be on a newline preceded by an asterisk (*), but there is no fixed format for this section.

[edit] Maintaining your contribution

[edit] Maintaining the changelog

With each update you make to your contribution you should add a corresponding changelog entry. The steps for adding to the changelog are largely the same as steps 2-3 above, with one minor difference. Instead of {{CL version|1.0}} you should use {{CL version|1.2|1.1}}, where '1.2' represents the new version number, and 1.1 represents the previous version number.

[edit] Finding your sub pages again

There are two methods of finding your sub-pages:

1. Simply add '/Features', '/Changelog' or '/Code' to the end of the URI in your browser's address bar when viewing your contribution's page.
2. Click the edit link for your contribution's page, scroll down to the bottom of the page and click the appropriate link under the Templates used in this page: section.