Forum OpenACS Q&A: Why is ad_parameter deprecated?

Request notifications

Collapse
Posted by Roberto Mello on
While going through acs-tcl/tcl/defs-procs.tcl and fixing
documentation, I just noticed that ad_parameter has the -deprecated
switch.

No explanation as to why it was deprecated was left. Does anyone know
why is that function deprecated?

Can we please leave a note on the ad_proc documentation section when a
-deprecated switch is used, explaining the reasons for that
function/method to be deprecated?

Collapse
Posted by Yonatan Feldman on
this was me. i thought i had put an @see comment in the documentation for ad_parameter but obviously forgot. there is a new parameter:: package in acs-tcl/tcl/parameter-procs.tcl the @see tag in ad_parameter should point there.
Collapse
Posted by Roberto Mello on
Yon, you did add the @see tags. I was the one who missed them while digging through the comments. My apologies.
Collapse
Posted by Don Baccus on
We should probably announce such changes so folks who know ad_parameter (or similar utilities) well enough to use them without looking at the code/api doc will know to switch.

Yet we probably don't want to clutter forums with posts for each and every such change.

Any ideas on how to more effectively communicate changes of this nature to our developer community at large?

Collapse
Posted by Lars Pind on
Mount a shared instance of lars-blogger and grant write permission to everyone with commit rights.

http://www.pinds.com/download/

/Lars

Collapse
Posted by Yonatan Feldman on
don: i was planning on announcing this but was waiting because i want to rename one of the procs, parameter::set_value, to parameter::set, but i can't yet because there is a bug in the aolserver namespace code that does not let me do that.

i submitted a patch to the aolserver folks but they have not applied it yet.

Collapse
Posted by defunct defunct on
Just wanted to add something....

Been a bit of discussion recently about renaming functions etc... and also there appears to be (forgive me if I've misunderstood) some effort to move existing functions to namespace style...

Given the effeorts made to encourage upgradescripts etc.. following release 4.5, are people going to offer some kind of upgrade for these kinds of funtions changes etc..?

Perhaps this has already been addressed, and I've missed it, but if not then can I please ask (assuming this is the case) why functions etc are being renamed etc.. without upgrade. Obviously theres not much point making an effort to provide database upgrades if lots of the code is just going to stop working...

Again apologies if I've missed something and its already been addressed..

Incidentally why renbame a function from set_value to set.. not sure I see why?

Cheers
Simon

Collapse
Posted by Don Baccus on
don: i was planning on announcing this but was waiting because i want to rename one of the procs, parameter::set_value, to parameter::set, but i can't yet because there is a bug in the AOLserver namespace code that does not let me do that.

That wasn't really my point, Yon, I was asking generally if anyone had an idea for making such announcements in a way that would be visible yet not clog the forums.

One could answer "finish setting up the CVS commit listserv" (which I hope someone finds time to do) but that's not a real answer, I've quickly learned to ignore most CVS updates because most of them don't contain fundamental API changes.

So I don't think that's the answers.

Lars's suggestion's an interesting one, maybe we should try it on the new website ...

Collapse
Posted by Jade Rubick on
I read through Lars' documentation, and I guess I still don't
understand what a blog is or how this would solve this particular
problem..
Collapse
Posted by Lars Pind on
A blog is short for a weblog.

http://pinds.com, http://scripting.com, and http://boingboing.net are examples of blogs.

A blog doesn't have to be maintained by any single individual. It can be maintained by a group of people.

In this instance, whenever someone makes changes of a general nature to the OACS tree, we'd post it to the blog, so other people could see what was going on.

We'd want to integrate with notifications, of course, but I'm thinking of doing that anyway, as soon as I get my own site upgraded to 4.5.

Collapse
Posted by Stephen . on
Why would posting to a blog be any different than posting to the bboard?  Posting this stuff to the bboard seems ideal.  It's not as if there's going to be a lot of traffic round here now that newbies, admins, designers etc. etc. will be moving to their own little hidy-holes.
Collapse
Posted by Lars Pind on
There are differences in presentation, in that you get the full body of the original posting at the top, plus there's more focus on the latest events. But there's nothing paramount.

Plus, a blog is cool ;-)

But if we did go with a bboard, I'd suggest a separate bboard for those kinds of "keep me posted on the latest happenings in the CVS tree" type things, which aren't too relevant to people who are just relying on the latest release as users.

Collapse
Posted by Jon Griffin on
change the core, put it on the board.

What is so difficult about keeping changes current, I mean really. 4.5 is barely out, everyone wants to change this and that for 4.6 and there are no upgrades scripts, no readme doc that explains all the ways my site will break when I upgrade and no good api browser that lets me look at this on another site (i.e. openacs) when I do the upgrade and find out my site is hosed.

Please lets think about the future in terms of upgrades as well as cleanups and "cool" new stuff.

Collapse
Posted by Stephen . on
This is not about stuffing developers email boxes with every last detail captured by cvs, in case you hadn't noticed Lars (and who could blame you?) we've now set out along the path of renaming every one of the more than TWO THOUSAND names in our Tcl api, FOR NO GOOD REASON -- and I'm pretty fucking pissed about it!

In what universe is it acceptable to rename an api AND NOT TELL ANYBODY?  Tough shit to fellow developers who collaborate on the toolkit, earning a living -- they'll just have to spend time scanning every source file and re-learn an api they've been using for the past 3 years.

Perhaps we should alert Jim Davidson who looks after AOLserver to the error of his ways.  His procs have been prefixed with ns_ for over 10 years now!  I mean, it's not even called Navi Server anymore, people will think it stands for Netscape or perhaps has something to do with Apple's Next Step api (another one!).  It's not even a functionaly descriptive prefix, it's pure vanity!  Just who do these people think they are, professionals?

I can't even believe I have to take the time to swear and shout to draw attention to that which is so plainly obvious if given just a moments thought, and why Roberto should have to grovel through the code, which is the only possible way he could @see the unsupported Java style doc note.

What exactly are we going to do about this?

Collapse
Posted by Jun Yamog on
I have to agree with Stephen on that.  Even though for example ad_conn became ad::conn even if ad::conn contains bug fixes.  Its kinda not easy for me to grep grep grep on my code.

I think better highlight on my top 20 list that what is listed on the list should not be applied on old code.  It must be only applied to new code.

Collapse
Posted by Roberto Mello on
Stephen,

Let's take it easy. I understand your frustration, but I think it's somewhat not justified. No official statement has been issued (that I've seen) by the release manager (Don) or the other gatekeepers about a complete renaming of the API.

I don't think that is what Yon is after either. He knows very well that we can't just make drastic changes. Rather, an incremental change is being made, and a compatibility API is left with a note that developers should be aware of the new one.

I'd recognize that we need to pay better attention to upgrade scripts and path. That's point well taken and I'm sure others have gotten that from this and other threads.

Collapse
Posted by Stephen . on
No official confirmation, what are you talking about Roberto?  Quite clearly, in the thread which you yourself started when you asked "should I put my procs under namespaces or not?" Don confirmed Yon's yes answer, and they're not the only ones.  If that's not a (bunch of) official statements, then what is?

In a thread a couple of days ago someone asked why some people use tabs to indent and some people use spaces.  Someone else joked that they were not going to get into that religious war.  There is of course a correct answer: you put aside your personal preferences and do whatever everyone else is doing, you follow the project standard.

AOLserver has a coding standard, the developers wisely decided to lift it from the Tcl code they were using rather than invent something new.  Postgres has a coding standard, they've even written their own tool which reformats the code for them to enforce it.  The Linux kernel has a coding standard, etc.  In other words, it's standard industry practice to follow a single coding style per project, for the very good reason that it increases developer productivity.

Now the toolkit has one more coding style, and is more inconsistent.  To regain consistency the rest of the API must be renamed; afteral what's so special about permissions and parameters?  Or, we've just decided that consistency doesn't matter.  Never mind that no one was asked, no one was told, the documentation has not been changed, the existing code has not been changed, there was no technical justification for namespaces, AOLserver has problems with namespaces...

I think my frustrations have been more than justified, Roberto.

Collapse
Posted by Andrew Grumet on
It's worth pointing out that ad_parameter does something really useful that parameter::get does not. Namely, it lets you override package parameters in a text file. This is useful for all sorts of situations where you have multiple instances of the same project and e.g. don't want to go mucking around updating database tables each time you refresh the staging server with production data. Amidst the rampant clutter in my brian I recall this old thread that had a lot of good ideas. I'm not sure these were ever implemented (Don?). Perhaps someone is interested. Just don't ask me how to name the new procs.
Collapse
Posted by Roberto Mello on
Steven, I think you're mixing two things in one:

In your previous response in this thread you said:

"we've now set out along the path of renaming every one of the more than TWO THOUSAND names in our Tcl api, FOR NO GOOD REASON"

And further in another response you claim that "Quite clearly, in the thread which you yourself started when you asked "should I put my procs under namespaces or not?" Don confirmed Yon's yes answer, and they're not the only ones. If that's not a (bunch of) official statements, then what is?"

You should notice that these are two different things, in my view, and that you're putting them in the same bag as if they belonged in the same bag: 1) Naming of FUTURE procs 2) *Renaming* *current* procs.

In the thread which you mention I started I asked what should I name for the _new_ packages I'm building. The answer to that was "use namespaces".

Then the ad_parameter question came along (also by me) and the issue of _renaming_ of the API came along, and it's _that_ issue that I said that nobody has said "YES, let's rename the whole toolkit to namespaces". And I'll say it again, I've not yet seen anyone saying that we should rename the whole toolkit API as you are claiming. What I have seen is people saying "Yes, use namespaces for your new packages".

There's an issue coding of standards to be resolved here, but I'll leave that for another thread.

Collapse
Posted by Don Baccus on
Quite clearly, in the thread which you yourself started when you asked "should I put my procs under namespaces or not?" Don confirmed Yon's yes answer, and they're not the only ones.
That was in regard to new development, you twit. By definition if the development in question is new you're not using its API so you have no code to change.

No one's proposing changing the entire ad_* API to use namespaces. If you'd been paying attention you'd see that I just recently added a set of procs for form handling, primarily "ad_form", that wasn't built around namespaces.

The OF folks made some incremental improvements to the parameter API. Incremental improvements are not a sin. Communication could've been better, maybe and advance "will people kill me if I ..." note so they'd know how people felt, but overall there's really nothing to complain about here.

And there's certainly no cause for you to extrapolate this into some horror story of toolkit-wide gratuitous renaming just to make your life miserable.

Collapse
Posted by Don Baccus on
It's worth pointing out that ad_parameter does something really useful that parameter::get does not. Namely, it lets you override package parameters in a text file.
We don't want to loose this, it's there because people have found it useful. Andrew's pointed out one case where this is true. I think it was CR Oldham who made this work but could be wrong, what I do remember was it was discussed in public and people wanted the functionality.

So incremental improvements are good, but removing functionality that people want is not an improvement. Can someone assign themselves the ask of making parameter::get honor text file params ala ad_parameter?

Or convince me (and apparently Andrew and undoubtably others) that we really don't want this functionality?

As far as coding standards being good ... yes, they are. That's why we've got the "20 do and don't" thread going.

Collapse
Posted by Yonatan Feldman on
andrew, don,

as soon as andrew told me about this i put the code back in to get the parameter from a file. looking at it now i realize why it's still not working, i am looking in the configuration file for a section called acs/<package_id> instead of acs/<package_key>. i will commit a fix for this as soon as i have it.

yon.

Collapse
Posted by Yonatan Feldman on
i checked in a fix to allow getting the value from the configuration file correctly. i moved the call to ad_parameter_from_file from parameter::get to parameter::get_from_package_key since you can only use a package_key to fetch a value from the configuration file anyway.

if it doesn't find it, it will revert to normal get by attempting to convert the package_key into a package_id via apm_package_id_from_key. one problem this has is that apm_package_id_from_key will barf if there is more than one instance of the package. what do people think about changing that function to "select min(package_id) from apm_packages where package_key = :package_key"? any objections?

yon.

Collapse
Posted by Don Baccus on
Thanks, Yon ...

As for the "min()" hack ... I'm not sure.  Maybe it *should* fail if you attempt package_key lookup and it has to go to the db and there's more than one instance?  I really have no idea which is best.  It needs documenting in either case, though.  Maybe logging a warning or something so at least folks know when this happens?

I'm just worried that this could confuse people who try to look up a parameter value by package key for a non-singleton package.  They would probably do this because they're either new to the toolkit or spacing out, and they'd probably test with just one instance mounted, and then later on they or someone else would run into the problem and be mystified ...

Collapse
Posted by Stephen . on
Roberto, although your original question was what should you name your future procs, the example given, permissions, is the renaming of an existing set of procs.  The example in this thread is again an example of trivially renaming an existing proc, ad_parameter.  No, this does not mean that *all* procs will be renamed, but some procs have been, and some more procs will be.

However, I then went on to explain that I think a standard naming scheme is important, why, and how I got the idea.  As it's such wide spread practice I assumed it was the general opinion here, which seems to be the case as there is now an effort to formally record such a standard.  If standard naming is important, and there is a new naming standard, then is it such a leap to believe that the work to rename some of the existing procs will be carried forward to the rest of them?

You seem to have missed it but I also then explained why I think *not* carrying through with a new naming scheme renders any notion of creating consistency through a standard naming scheme obsurd, as the opposite of the desired effect is created.  This is another reason why I thought the plan must be to rename all -- or should I say a large percentage of -- the old procs.

Don, I think your right I must be a twit because I'm still confused.  You mention your newly developed proc, ad_form as an example which does not use namespaces.  But you also say namespaces must be used, when Roberto asked about developing new procs.  Do you mean to say that either the old established style with underscores or the new namepsace style are both acceptable?  What is the goal of introducing another naming style and enforcing it incosistently?

Could we also please have a commitment, folks not just a begruged shrug, to communicate this sort of stuff in a timely manner, with enough facts and some semblance of reasoning as appropriate, so that everyone is kept in the loop and inteligent desision making, where necessary, is actually possible?  This is my main point of frustration.

Collapse
Posted by Jun Yamog on
After this thread ends.  Can someone post here the final guideline regarding name spaces or proc names.  I would like to have the "20 things to remeber..." to be as correct as possible.
Collapse
Posted by Don Baccus on
Stephen ... it's an evolutionary process.  I do think it would be good for new packages to use namespaces in a straightforward way (I personally think the style used in acs-templating is overkill).

While I think new packages (real live APM packages) should use namespaces my own thinking isn't as clear in regard to the acs-tcl library.

Originally aD had the tendency to stuff just about every ad_* named proc into one or two files.  With later 3.x and 4.x work people started paying more attention to grouping logically-related procs into logically-named files ("text-html-procs.tcl", for instance).  But it's still pretty messy.

But we can't really do a massive reorganization of this stuff, we don't have the resources to change all our own packages (or at least ISTM there's more important things to spend those resources on) and of course we can't break everything ever written by our user community.

So I guess my own thinking is that restraining ourselves from renaming stuff in acs-tcl/tcl and other central services is something we should consider.

While still encouraging namespaces for new packages.

Comments?

Collapse
Posted by defunct defunct on
Sounds fine Don....

Main concern is not to breal existing code, but I do agree that new stuff should use namespaces (even if it doesn make everything look like a giant PERL script ;)

Is there a migration step we could use for some of this? i.e. create namespace versions of existing stuff whilst keeping the originals.. new installs etc could perhaps choose not to install the orginal stuff... whereas existing systems would still have access to old functions, but also have new ones in parallel... although not ideal it may be a gradual way to convert whilst allowing new systems to use new stuff only...... ?

Collapse
Posted by C. R. Oldham on

Whoa, I step away for one day and look what happens. :-)

Just wanted to set the record straight:

Don Baccus wrote: CR Oldham who made this [ad_parameter grabbing values from a file as well as a database] but could be wrong.

Actually the code to do that was in the toolkit from the beginning. What I did was add functionality to the APM pages that shows when a parameter in the database is being overridden by a parameter in a parameter file.

Collapse
Posted by Arjun Sanyal on
Namespaces are a powerful organisational tool for APIs. To give an
example from my own work on the new-portal package, it currently has a
single namespace "portal::". But portal is fairly complex, with a
number of distinct "objects": portals, portal elements (html boxes on
a portal), portal datasources (the stuff that fills a portal element),
portal layouts (like 1 column or 2 column), and portal themes (a style
of decoration). With one flat namespace, or the old style of having no
namespace at all, the multitude of procs makes for a mess of
code. Also, It doesn't help matters that all the procs are in one huge
file. So, just as splitting up this moby tcl file into smaller object
specific files is a boon to comprehension and maintainability, so is
splitting up the namespace into subnamespaces like portal::element::
and portal::datasource::

That's for new code, but what about old ad_* code? Here there are
some facts about the old code:

1. many procs we inherited from ad_ are badly designed, named, and/or
organised and, not to mention, rather buggy.

2. namespaces are widely used in the old code. A quick grep through
the tree for "namespace eval" will show dozens of uses of namespaces
from aD'ers. Notably, both acs-templating and cms use subnamespaces
extensively.

Parts of the core ad_* api need to be refactored and fixed if oacs
is to improve as a toolkit. I doubt there is much debate there.

If done with care, fixing parts of core that are badly needing repair
using new namespace procs will:

1. NOT break old code that relies on an old ad_foo proc. the ad_foo
proc will work just as if no code was added (with probably with less
bugs)

2. NOT "replace" or "remove" the ad_foo proc until developers have had
enough time to become familiar with the new namespaced procs and
proper warnings have been issued to everyone.

There are two things wrong with what you call a "trivial renaming of
ad_parameter". A cursory glance at the code will show that: First, the
work done on the parameter namespace was not trivial. It was an
thoughtful cleaning and refactoring, adding such improvements as the
exclusive use of named parameters. It's more orthogonal and
explicit. Easier for newbies and old hands alike. Second, what one
intuitively thinks of with "renaming", i.e. a removal of the old proc,
_did not happen_. ad_parameter is still there functioning exactly as
before. Developers can use it without even knowing that the
parameter:: namespace exists.

With this amount of care given to adding cleaner, less buggy, and
easier to understand namespaced code in the core, a core which is
_already_ a mix of ad_ and namespaced procs, namespaces are a win,
for old and new code alike.

Collapse
Posted by Don Baccus on
"not breaking existing code" and "fair warning before removal" are the important aspects of such changes, of course.

Thanks for the well thought note.  I think we're fairly well on the same page (you and I, don't know about the rest).

I said it's an evolutionary process and that we should restrain ourselves from renaming just for renaming's sake (I wasn't implying that the new parameter namespace fell into this category, I know you added functionality etc).

You're saying there are a lot of things in the utilities space that could clean-up work, refactoring, and outright bug fixing and that while doing so using namespaces to better organize the code would be a good idea.

I don't see any large-scale disagreement in those two paragraphs.

Especially since when doing such cleanups and refactoring we want to encourage getting it right even if the calls change.  This frequently implies adding a new proc (so you don't break the old) and there's no reason to maintain the old name style for the new proc.

One think that's needed is a well-documented way to deal with deprecated procs and their disappearance.  Removing them one or two releases in the future after ample documentation that they've been deprecated and after explaining why.  That sort of thing.

Collapse
Posted by Michael A. Cleverly on
don: i was planning on announcing this but was waiting because i want to rename one of the procs, parameter::set_value, to parameter::set, but i can't yet because there is a bug in the aolserver namespace code that does not let me do that.

i submitted a patch to the aolserver folks but they have not applied it yet.

Whoa... hang on. I imagine that rather than a bug in AOLserver's namespace code, the bug is in the "redefinition" of the Tcl command set, at least within the scope of code executing in the parameter namespace.

When code runs inside the scope of a namespace commands (which are not themselves qualified with a namespace) are searched for in the current namespace, and, if nothing is found, in the global scope.

So if you define a namespace::set proc, then you need to explicity qualify all instances of set in your code (that runs in the same namespace) to use the global set, i.e. ::set.