The following Codex is a collection of loose "guidelines", intended to maintain an organized structure for elaborating Open Source Macro Projects. The Codex guidelines should not keep away or restrict anyone from developing or contributing codes, rather they should provide a base for a unified communication template across (more or less) complex projects. The developers are thankful for every contribution and adherence of an organized structure.
New Projects
Of course everyone can post his/her macro codes here. It's a contribution to the community and a benefit for everyone.
- Make sure the code is developed entirely by yourself, to prevent copyright conflicts. The macro should also be something which hasn't existed before; there are commercial macro sellers who naturally can get very angry if they conceive suspicion that their product might be copied.
- Please make your project accessible to the public only if you feel comfortable with making your project Open Source. If you are not sure about this, you can get suggestions in a new thread, here: Code Snippets Feedback.
To avoid messing up the existing stucture, a new project should be started with the following structure:
- The main page for all projects is the page Open Source Macro Projects, and the new project can be grouped as subpage of this project page, with the name of the macro. This introduction page should provide some basic information:
- A short introduction what the macro is used for and what it does
- one or more screenshots
- a link to the thread, where the macro can be discussed, optimally here: Code Snippets Feedback
- the current release, with date (so everyone can see when it was lastly elaborated) and the version. For more information about versioning you should read the paragraph "Versioning"
- current features
- on which operating systems and Corel versions it is tested by now
- if the macro uses VBA or Windows API calls, the dependent and necessary dynamic link libraries should be listed (important for developers)
- and finally, the license under which terms the macro and the code is published and accessible.
- Give your project a descriptive and unique name, such as "Open Type Wizzard" or "Meshfill Making Macro".
- All published codes and files should show a copyright notice of the copyright holder, in order to avoid piracy.
- Under your macro's main page there can be several subpages. The important ones are:
- "Resources". This page provides the current and older versions with the dates of publication. The versions should be linked to the file attachments (You can upload your files by adding ".txt" at the end, or upload them in your own media gallery)
- "Bugfixes". This page should list all fixed errors and new improvements. See "Versioning" for more details.
- Optionally, depending on the (Open Source) License under which you provide the macro/code, it is necessary to publish the source code to make it readable for everyone. That is, the page "Source". Don't be afraid the code could be altered in a senseless or silly way: this wiki provides tools to revise applied changes.
Contributing to or developing existing Projects
To contribute improvements to an existing project, the thread (linked on the macro's project page) should be used. The same for feedback or suggestions, if you don't dare to develop a macro yourself, and of course if you encounter bugs and errors. That helps keeping the structure of the project page clean and easy to follow for both developers as well as users.
A development process can get very complex, so a good versioning can help keeping track of the main macro development.
Versioning
There are many ways to elaborate or improve a code. The following is rather simple; for example a macro version can be separated into three modification categories:
- Major version: is the first digit in the version number and expresses if the macro is still in Beta State (version less than 1.0.0) or a Release Candidate which has reached all development goals for a major version (version 1.0.0, 2.0.0 and so on).
- Minor version: is the second digit in the version number and expresses the milestone it has past. For a macro in progress, unlimited milestones can be defined (after 0.9.0. comes 0.10.0). Milestones are important improvements in functionality or new added functions. Commonly developers collect enough reqirements to reason a new major release and group them in milestones as temporary development goals.
- Patch version. This one is relatively independent to the first two version numbers and expresses important bug fixes. The increase of the patch number stops with the final Stable Release, where all bugs are fixed.
- A version that has been published the first time, is an Alpha Release, until someone picks up development.
Branches
At a certain state in development it may happen that the macro isn't backwards compatible anymore. For example if a macro has run smoothly under a Win XP OS and some changes were done to get it runnung on Win 7, but now it isn't usable in XP anymore. It is understandable that a macro should run unter as much environments as possible, but sometimes this can't be observed. In this case the development should be branched to a new sub project, maintaining the version number. Then it is ensured that a wide range of users can use a macro.
Copyright
If you decided to work on an existing projects, make sure to respect the copyrights of your co-developers. Copyright notices in the codes and files should remain and may not be altered. Of course you can add your own copyright data such as name, website or contact email, when you've contributed to a project.
Hijacking projects or copying them (no matter if intended as commercial or non-commercial) isn't allowed (and to be honest: not very clever...).
Have fun to code, learn and use!