How To Make Contributions
Posted 21 December 2002 - 22:45
When a new contribution is made available, a package is created that holds the description and file. This file can be seen as v1.0 of the contribution made.
When an updated contribution is made available, it should be added to the original package. This allows different versions of the contribution to exist in an easy to find package.
Clicking on "Contribute A New Package" will enter a new package into the contributions list. Clicking on "Add A File To This Package" will add a file to an existing package.
Both methods will show the package on the Newest Contributions list as it has been the latest package to be modified.
Since a package can hold multiple files, it is a good idea to enter a clear title for new packages without the version number. For example, if an updated categories box is to be contributed, the ideal package name would be Different Style Categories Box instead of My Categories Box v1.0.
Additional files to this package should include the version number in their title, as the title to the files are shown when viewing the package.
Posted 12 January 2003 - 07:50
Contributions that obey these conventions will not only be more robust and therefore valuable to a larger subset of osC installations, they stand a greater chance of being maintained and updated for the moving target which is osC, and for being incorporated in future milestones and releases.
Many of us who are eager to make contributions that follow "tep standards" have sometimes had to infer what these standards are, by studying the developers' code and then imitating it. To understand and operate within the database design, we guess at it by reviewing the table definitions and the SQL queries embedded in the code. The community would benefit by bringing these rules out of committee and into the public, so to speak. It took me months of daily review of coding, and browsing the forums, to learn the essentials that could be more readily available. I encourage others (and the core developers) to extend this thread regarding other reliable sources besides what I identify in this post -- not a discussion of their details or merits, but just how to find them.
The team released a significant revision to the standards document just a couple of days ago:
It is an excellent starting point for would-be contributors, and its availability is hereby applauded.
Naming and hierarchy conventions
If there is a more definitive source for the script naming and folder hierarchy conventions than familiarity with the CVS itself, I'd like to know where it is. But you can study the code and see that catalog/ and admin/ have similar but distinct folder hierarchies. For instance, while there is an immediately apparent similar hierarchy in admin and catalog, closer inspection reveals that admin/includes/functions/ has different contents than catalog/includes/functions/, and admin/includes/configure.php is not identical to catalog/includes/configure.php. These hierarchies are important to the modular design of osC, and fitting contributions properly into them requires learning them. Operating scripts' language-specific displays in both admin and catalog should be declared by define statements with the same name as the script, but placed in /includes/languages/<language>/. Classes should be defined in scripts with the name of the class and placed in /includes/classes/. Some of these conventions are in the standards document referred to above. There are many more such conventions that are unpublished but necessary to the modularity of osC, and unless we know them we cannot conform to them; without conforming to them, our contributions are inherently less valuable.
Use of tep_ (osc_ when 2.2 is final) standard functions
As far as I can tell, there is no better way to learn what functions have been standardized across osC than by studying the code in the admin and catalog functions directories, especially general.php, database.php, and html_output.php. Contributions should use these functions exclusively for their intended purposes, to maintain modularity, portability, and longevity, and thereby serve a wider user population. A handy index of these functions, their parameter options, and their behavior, would be a significant boost for the coding community.
Database structure and entry description
We review install/oscommerce.sql, and everything about the tables is there. But the intended purpose and control of each table entry can only be inferred from the interpreting the way the tables and entries are used by the existing code. Contributions may misuse or damage database contents, and interfere with other store features, if the entries are not well understood.
It is exciting to see open source development really working on such a scale, and a privilege to be a part of the contributing community. Let's continue to improve the quality of our contributions by learning and applying the conventions and standards which have been wisely adopted by the core developers.
Posted 22 January 2003 - 07:52
I certainly appreciate your concerns about modularity, stability and the upkeep of conventions. It would in deed leed to a better system.
On the other hand, the emphasis on the 'perfect' coding standard might encourage less experienced developers and, most of all, users to make their spontaneous ideas available to the community.
I, for this matter, can hardly write php, never mind fully understand the tep-methods. But I'm a user with a clear idea of how certainl shop functions will have to work. If I ever make a proper contribution, it probably won't be spotless. Should I not make it available?
Perhaps, there could be sort of a 'mentoring group' where beginners can post their contributions for polishing up. More experienced developers can then comment or contribute some corrections. Then, the code will be fantastic and the community still benefits from the maximum base of ideas.
In the end, I'd rather have a sloppy solution to an urgent problem, than none at all.
But, again I am NOT IN TOTAL disagreement.
Posted 26 January 2003 - 02:37
- ce7 likes this
Posted 20 February 2003 - 07:40
Of course all contributions should be accompanied by a readme.txt or install.txt, which clearly describes the function, content and structure of the contribution, then lists steps for its installation. The contributor should also note the compatibility constraints (e.g., works only with checkout system post 20021101) or certification (e.g., tested with MS1).
Let me take this opportunity to stimulate some discussion on conventions (or at least suggestions) for packaging contributions.
Posted 03 May 2003 - 05:43
it's very nice to see the changes made and also helps understand it more cause whatever wasn't explained in the readme.txt file, was asked there or can be asked there and get an answer... but I do prefer the way contributions are indexed here, cause they're in order, not by most-recent-replied-to-order
a nice solution would be the contributions section that's here now, but with the possibility of replying to it like in a forum topic... I've seen some pages have a "comments" system at the bottom that lets the reader contribute
another nice feature for the contributions area would be "search" (in name or description) and "sort by" (date, contributor...)
Posted 03 May 2003 - 11:07
*Creator Options (Update, Correct etc..)
*Creator Download Count
Posted 10 June 2003 - 20:30
I made buttons in greek language and i want to store them in contributions section.
Can anybody tell me the way that i can do this :?:
I didn't saw any link on OsCommere page that say's (for example) submit your contribution
Please let me know if is a special section that i can do this :idea:
(forgive my english. I know arent the best :wink: )
Posted 11 June 2003 - 22:33
On this page there is a great big link to "Contribute a new package" on the right side under the list of newest contributions:
The correct Package Category for a button image contribution would be "Images".
You have apsulutely right.
I must be blind :shock: I din't saw this man.
Thanks for given me the lights :!:
Posted 11 June 2003 - 22:35
Sorry for my english /biggrin.gif' class='bbc_emoticon' alt=':D' />
Posted 10 July 2003 - 17:46
Posted 10 July 2003 - 22:49
able to keep track of how many people have downloaded a contrib.
i agree - i have received responses on my contribs, but hard data would help guage its acceptance.
Posted 18 September 2003 - 12:49
Its possible I misunderstand the versioning system, but I see some inherent problems with the way some contributions are labelled.
I see osCommerce as a platform with differing versions, reliant on dates with regards to version numbers. For example, the CVS tree, being the most up to date. Now, I have seen various contributions explain that their contributions work with CVS 2.2, although will you may have difficulties with later versions after the next update (not to 2.3, maybe just a few weeks if the CVS tree is altered slightly).
Now, this is an inherent problem I believe in writing contributions. If a module is being written, that relies on no other files outside of the standard module/ and languages/ directories, I imagine there should be no difficulties.
But since contributions frequently make changes to pieces of code, they also become reliant on the same variable names the same files etc.
These contributions should still work, but they don't.
Now maybe I'm biased because I installed MS2, but I've looked at other projects and they do not seem affected in the same way, largely because they used a Milestone edition to make adaptations and add-ons for.
One thing is clear, a lot of contributions are not clearly labelled as being for use for MS2 or MS1. At the moment all contributions seem to be labelled as CVS2.2 which is not helpful (since sometimes a date is needed to indicate whether it is certain to work or not even if you are using the CVS version), also the date in some projects, seems to alternate between american date format mm/dd/yyyy and dd/mm/yyyy which would make it confusing other than the fact the new items are at the top. Consistancy is the key!
Anyway, thats my five pounds worth. If I'm wrong about any of this I apologise, but I won't be slighted if you point out any innaccuracy on my point. As well, this is not meant to be critical of those who have written contributions. Contributions are (IMHO) the most important thing about osCommerce. Tailoring the application to a persons individual needs.
Posted 06 January 2004 - 18:55
Posted 21 February 2004 - 17:51
Just from my experience it would make finding the correct forum to post and/or get help for a contribution much easier /smile.gif' class='bbc_emoticon' alt=':)' />
Posted 22 April 2004 - 13:32
What would be cool is if the submission of a contribution automatically created the announcement topic and support topic, and inserted appropriate links to each.
I would also like to see a way to clean up contributions - removing buggy versions, for example.
Login Page a la Amazon
Protection of Configuration
Embed Links with SID in Description
Posted 24 April 2004 - 23:10
To All: take caution and even seek advice when choosing the Category into which you make your contribution. There are some notable mis-categorized contributions that have not gotten the attention they deserved when people didn't find them in the expected place. Take for instance: AuthorizeNet Consolidated, which should be in Payment Modules, is in Credit Modules; and Discount for Payment Type, whose description even acknowledges it creates an order total class, is in Credit Modules but should be in Order Total Modules.
Unfortunately, there is no present means for transferring contributions to their correct category.