This posting is a short description on how contributions should be made. It will be added to the Contributions section when the "adding" pages have been updated to be a little more user friendly.
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.
Latest News: (loading..)
0
48 replies to this topic
#2
Posted 12 January 2003, 07:50
While the subject of making contributions has our attention, contributors should be urged to program their submissions in accordance with the design standards and practices established by the core developers; to name the scripts and package them by the same conventions and directory hierarchy as the CVS; and to employ tep_ functions for database access, html output, email, dates and the various other purposes for which they have been implemented.
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.
Coding Standards
The team released a significant revision to the standards document just a couple of days ago:
http://cvs.sourceforge.net/cgi-bin/viewcvs...atalog/STANDARD
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.
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.
Coding Standards
The team released a significant revision to the standards document just a couple of days ago:
http://cvs.sourceforge.net/cgi-bin/viewcvs...atalog/STANDARD
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.
#3
-
- Community Member
- 93 posts
- Real Name:Waldschrat
- Location:Liverpool, UK & Ravensburg, Germany
Posted 22 January 2003, 07:52
Dear Fritz,
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.
Thanks!
:wink:
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.
Thanks!
:wink:
#4
Posted 26 January 2003, 02:37
I wrote a dev contribution management center a couple of years ago that did this and created a single thread for visitors to read/post notes regarding the contribution as well as various additional modifications of it. We found it very helpful to have a thread of notes regarding that specific package. If interested in seeing it in action for ideas, I'll be glad to put a copy online to demo the concept.
#5
Posted 20 February 2003, 07:40
Besides coding conventions, there is also an issue regarding how contributions should be packaged. Brad Waite and I have just had a private colloquy about this, on a contribution in which we collaborated. He preferred to post diff files, while I had posted replacement files in nested directories. Each package appeals to a different audience, so I proposed to release the contribution both ways simultaneously.
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.
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.
#6
Posted 03 May 2003, 05:43
I like very much the way www.yabbse.org releases new mods for its forum... they post a new topic for each mod and then users comment on it and bugs and solutions and code and stuff
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...)
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...)
#8
Posted 10 June 2003, 20:30
Hello everybody.
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:
Thanx.
(forgive my english. I know arent the best :wink: )
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:
Thanx.
(forgive my english. I know arent the best :wink: )
<?php echo "WiseMan"; ?>
#9
Posted 10 June 2003, 20:55
On this page there is a great big link to "Contribute a new package" on the right side under the list of newest contributions:
http://www.oscommerce.com/community/contributions
The correct Package Category for a button image contribution would be "Images".
http://www.oscommerce.com/community/contributions
The correct Package Category for a button image contribution would be "Images".
#10
Posted 11 June 2003, 22:33
Quote
On this page there is a great big link to "Contribute a new package" on the right side under the list of newest contributions:
http://www.oscommerce.com/community/contributions
The correct Package Category for a button image contribution would be "Images".
http://www.oscommerce.com/community/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 :!:
<?php echo "WiseMan"; ?>
#12
Posted 20 June 2003, 05:02
how do i suggest a contribution to be included in the core package? i created a template system
http://www.oscommerce.com/community/contributions,1260
http://www.oscommerce.com/community/contributions,1260
#13
Posted 10 July 2003, 17:46
Perhaps the wrong forum for this, but: I think it would be cool to be able to keep track of how many people have downloaded a contrib. I made a (somewhat pathetic) enhancement to a contrib a while back, and to my surprise, I have gotten some feedback from people actually using it. It would be cool to know how many people have downloaded it.
#15
Posted 29 July 2003, 12:55
the only thing i see here:
http://www.oscommerce.com/community/contributions
is add-ons for CVS.
any help appreciated
http://www.oscommerce.com/community/contributions
is add-ons for CVS.
any help appreciated
#16
Posted 18 September 2003, 12:49
Maybe its me, but a lot of contributions I see I have difficulties with, purely because of the version they are implemented on.
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.
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.
#18
Posted 21 February 2004, 17:51
One thing I've noticed is that it is very hard to find the support forum for some contributions. Is there anyway that on every contribution's download page there can be a link at the top to that contributions support forum? (And visa versa, each support forum could use a link to the contributions download page).
Just from my experience it would make finding the correct forum to post and/or get help for a contribution much easier
Just from my experience it would make finding the correct forum to post and/or get help for a contribution much easier
Recover Cart Sales / PayMeNow (Merchant Partners) / Fix Order Status / Zero Weight Skips Shipping / Re-Arrange Order Creation
#19
Posted 22 April 2004, 13:32
What you have here is the classic "chicken and egg" problem. You can't reasonably create the forum post until the contribution is made (and a URL assigned), and can't point to the forum topic in the contribution until it is created! Yes, you can go back and edit your post, but that looks awkward.
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.
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.
Steve
Contributions:
Country-State Selector
Login Page a la Amazon
Protection of Configuration
Updated spiders.txt
Embed Links with SID in Description
Contributions:
Country-State Selector
Login Page a la Amazon
Protection of Configuration
Updated spiders.txt
Embed Links with SID in Description
#20
Posted 24 April 2004, 23:10
stevel: it does not "look awkward" for a post to be edited, in fact it shows you have taken the care to make corrections. Just be glad you have this capability, we didn't used to.
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.
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.
