Latest News: (loading..)
Harald Ponce de Leon

How To Make Contributions

51 posts in this topic

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.

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

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:

Share this post


Link to post
Share on other sites

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.

ce7 likes this

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

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...)

Share this post


Link to post
Share on other sites

The main things I think would be good are:

 

*Serach

*Sort By

*Creator Options (Update, Correct etc..)

*Creator Download Count

*Rating

*User Comments

Share this post


Link to post
Share on other sites

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: )

Share this post


Link to post
Share on other sites
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".

 

You have apsulutely right.

I must be blind :shock: I din't saw this man.

Thanks for given me the lights :!:

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites
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.

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

I have scoured the community site and have been unable to find any documents describing the API for making a contribution package. Am I missing something? Any and all help will be appreciated.

 

Andrew

Share this post


Link to post
Share on other sites

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 :)

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

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.

Share this post


Link to post
Share on other sites

Since there is some comment about what would be good to enhance contributions, let me add my penny's worth:

 

Even though it is a lot of work for the contributor, all contributions should be submitted with a complete list of "find this" then "replace with or add that" changes to each and every module to which it applies. The reason for this is that most contributions seem to be written for an unmodified system. For modified systems, installation by simply copying various php modules does not work. And, in my case at least, my system is quite modified (I flail around a lot.)

 

There are some modules I'd like to include, but the effort to try to figure out what was changed, particularly since I'm not sure of exactly what the starting point was (although, usually it is MS2.2 or MS2.1) is prohibitive.

 

CharleyShipman

Share this post


Link to post
Share on other sites
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.

Don't know if awkward is the right word, but editting the post to link the contri, annoucement and support thread to each other indeed is a real pain. Even almost impossible sometimes, when the forums are a "bit" slow.

 

I think automatic linking/setup is a must, at least from the contrib download to the to the support thread.

Share this post


Link to post
Share on other sites
There are some modules I'd like to include, but the effort to try to figure out what was changed

doing a file compare to your "starting point" would give you this info I suppose.

(and after checking carefully it's all correct, you can upload that yourself as an update to the contribution if you think it's usefull for others too)

Share this post


Link to post
Share on other sites

I'd like to add what is important for me regarding the contributions.

 

(apart from coding standards and documentation explaining how to implement them)

 

I thinks it's really important to be able to rate contributions, there are some that are very similar and it's difficult to choose between them. I don't have the time to try a contribution, get it to work and then uninstall it without too much fuss.

 

Secondly, where possible, it would be great to see a screenshot. It really helps to see what the contribution is aiming to do, and it often gives an indication of the level of quality of the contribution itself.

 

 

Regards,

 

 

David

Share this post


Link to post
Share on other sites

Reading over this thread I have seen some really good suggestions for contributions. I must agree that a screen shot does wonders to make sure that everything is how it is intended to be. A list for compare and replacing of code has been great to find in many contributions. Even pages that have been done from a clean install and put into their respective folders helps.

 

The submission and forum linkage is a brilliant idea, as well as rating and download count.

 

Here I think so many will agree with me.

 

The contribution section needs cleaned out !!!!!

 

Contributions that are years old that are already a part of OSC, are clogging the contribution sections.

 

Contributions that have been updated version by version with old versions left on the list. Or fixed bugs that don't even tell you what version the fix is for till you download and open it up (wasted time and bandwidth)

 

Double files in some of the newer contributions.

 

The contribution section needs more of a break down of the types of contributions.

 

for example

 

Buttons ... Make a list just for buttons

 

Admin section ..... listing for admin section and a break down of sub cats.

 

If the contribution section was ran like the osc cart it would be a wonderful thing.

 

Just my 2 cents worth

 

Kel

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!


Register a new account

Sign in

Already have an account? Sign in here.


Sign In Now