proposal for rules of deprecation of Lua API stuff

[hoijui]

i would say we vote on this proposal in the next engine dev meeting. so if you have suggestions for change, maybe just post here, and i will update it.

(i made this same post in an other thread already, but though it makes more sense to have it in a separate one)

i propose...
that when stuff like tags get deprecated:

• a "convenience" thing gets added, that makes them work as they did before
• it gets marked as deprecated in engine code (together with the date of deprecation)
• it gets an entry in the changelog
• a description of why it was removed, and how to fix related lua code has to be provided somewhere .. not sure where best.. probably in a comment in code, next to the @deprecated tag?

all this has to happen at the same time. this makes it most easy and least painfull for the engine dev doing the change, and most easy to track and understand later on.

at most once a year, there will be an engine release where these depreacted things get removed for real, and only those that were deprecated at least 6 months before that release.
This release will of course be announced as a special release in this sense, and a list of all removed tags with the description will be added (actually, we could theoretically just link to the one commit that removes all of them, as it also contains the descriptions that explain how to fix code, if that is in engine code as comments).

this leaves at least a chance for different engine releases to run a single version of a mod, and is therefore kind of a nessesity for multi-engine-version support too. it also means casually maintained games are less painfull to play, as once fixed, they might run for half a year on latest engine versions (in average).
game devs could decide to use newer engine versions when they please, and roll back on an older one if the new one is too buggy.

the added ugliness that "conveinence way" code adds to the engine is negliable. it is clearly marked, little, isolated code, that can be removed without doin other engine internal changes. that is the most beautiful of all the ugly code that spring has, and .. yeah it has other stuff.

[zwzsg]

I am glad some engine developpers understand the importance of having a stable engine-to-game interface. Thanks!

[Pako]

Code: Select all

function widget/gadget:GetInfo()
  return {
    name      = "UnitDef tags",
    version   = "0.5",
    desc      = "Set backward compatible tags for UnitDef like isCommander",
    author    = "Pako",
    date      = "2011.12.30 - 2012", --YYYY.MM.DD, created - updated
    license   = "GPL",
    layer     = 0,	--higher layer is loaded last 
    enabled   = true  --  loaded by default?
  }
end

UnitDefNames['armcom'].isCommander = true
UnitDefNames['corcom'].isCommander = true

 for id,Def in pairs(WeaponDefs) do
   Def["areaOfEffect"] = Def["damageAreaOfEffect"] 
    Def["maxVelocity"] = Def["projectileSpeed"] * Game.gameSpeed
 end

Actually compatible Lua Def tags are easier than easy to set up with the current code, if not for the COMPLETELY BRAINDEAD WAY OF LEAVING THE DUMMY TAGS IN ENGINE. You can easily set yor custom UnitDef tags in the Lua Def table if there is no colliding engine tag and it is maybe 10X faster too because no need to call for engine to retrieve the data. Also once set in anywhere in that Lua environment all widgets/gadgets see it.

[FLOZi]

+1 for this suggestion hoijui, I hope we can have a civil and serious discussion about it.

[Forboding Angel]

+1 to hoijui, z and flozi.

Pako actually has a pretty neat suggestion. Perhaps when a tag is depreciated, you could move it to an engine gadget in basecontent that basically provides a workaround. It would be easy to sanitize that on a schedule.

I realize that I'm probably over simplifying it, but wouldn't that make everyone happy if the stuff could be removed from the engine and inserted into lua (the removed on a yearly/bi-yearly schedule)?

Now, is what pako and I talk about actually doable?

[FLOZi]

A gadget would be preferable to the _posts files too - most serious games already have their own custom versions of these and copy pasting bits in will become a chore compared to including one file from LuaGadgets/.

Not to mention that they themselves may need to change in the future anyway (c.f. various discussions between zwzsg and jk).

[knorke]

Sometimes tags are not simply removed but changed to work different.
For example replacing depthmod=number with depthmod=table. (in movedefs)
That breaks existing games but sometimes is worth it and easy-ish to fix.
Not sure if waiting 6 months for this would have helped anyone?

Another example: The removing of table.n
That was announced several weeks ahead, with examples and everything and still it broke some games when the new engine was released. (because some gamedevs did not bother with it.)

So I think super long warning times like 6 months are not helping.
What however is helping are instructions how to get the old behaviour. (eg what Pako posted here for exploding-piece-CEGs:: http://springrts.com/phpbb/viewtopic.php?f=14&t=27554)
Though such fixes are often quickly done by non-enginedevs, which is sufficient (?)

---

desc = "Set backward compatible tags for UnitDef like isCommander",

That looks good, I did not know those tables were writeable. Though widgets could accidently overwrite things(?)
Also when widgets do UnitDefNames['armcom'].blabla and then the engine introduces a tag named blabla, wouldnt that be problematic? (in the same way engine currently "blocks" some tags)
Seems better if games/widgets used the customparams table.
Forb:
Pakos widget has "armcom" etc. in it, so it can not be in basecontent because it is game specific.

Some bugs could probally be caught if a week before a release a "final testversion" was posted?
eg http://springrts.com/mantis/view.php?id=3019
<[LCC]Pako> the change was made only day before release
That seems like something that could have been avoided.

tl;dr:
The 6 months "grace peroid" does not seem usefull to me, imo do changes asap and just improve documentation.
This is somewhat related: http://springrts.com/wiki/EngineChangelogForContentDevs

[smoth]

I am with knorke. Gundam isn't broken because I could not adjust to the new engine, I had ample help with that from people's posts on the forum. Gundam is broken because I keep working on new features and those introduce bugs which have to be squashed and so I have not released because I am fixing my own bugs

[Forboding Angel]

Whereas I, on the other hand, have been doing nothing but damage control ever since 87 came out. It's been one damn thing after another, and these aren't really things I could have prepared for because pretty much most of it was blindsided. I still don't have a solution to spring isolated using hardcoded springsettings values.

Arugh, this release has been a frigging disaster.

I have spent no less than 20+ hours cleaning up messes caused by this engine version. That's pretty messed up.

Yes, the depthmod stuff was necessary. Now junk like that can be announced in the forums. That isn't a big deal. The .n stuff could have waited? or not? Was it absolutely necessary to have it done at that release?

This doesn't HAVE to be black and white. Can't it have some gray in it too?

[Pako]

Another example: The removing of table.n

(eg what Pako posted here for exploding-piece-CEGs:: viewtopic.php?f=14&t=27554)

Actually was made by engine dev, I just accidentally found it. The problem was/is most games have their custom unitdefs_post.lua which can't load the unitdefs_post.lua from basecontent which would had the backward compatible code.

Though widgets could accidently overwrite things(?)Also when widgets do UnitDefNames['armcom'].blabla and then the engine introduces a tag named blabla, wouldnt that be problematic?

No, it is all soft Lua.

<[LCC]Pako> the change was made only day before release

Actually week before. It broke AoE and blast radius widget.

The 6 months "grace peroid" does not seem usefull to me, imo do changes asap and just improve documentation.

+1 Even shitty changes could be changed in couple of minutes if they were documented better.

Gundam isn't broken because I could not adjust to the new engine

One night after the engine release at december the biggest game in lobby was these Japanese guys trying to get a Gundam game started for hours, I spectated few. They game was completely broken and they were glueless what happen. I asked in zkdev how to set Springie to old engine but no-one knew then. There went 100% of your player base.

I hope we can have a civil and serious discussion about it

If I shat behind your door so that when you open door it sweeps over you porch, would you keep a serial face and serial discuss about it?

[smoth]

someone is mad ya'll

[hoijui]

it feels like knorke and smoth did not read my post:
it is not about longer warning times, but about keeping multiple releases as compatible as possible, and introduce changes in blocks.
and as i already described, it is a nessesity for making multi-engine support much more useful. also, the way i described seems like a quite good way of documenting it.
maybe every commit that introduces a deprecation (inclduing the in-source comment that describes the why and how to workarouand and may contian workaround lua code) could be "tagged" with [deprecated] or the like (in the commit message), additionally. it yes, it would also be in other places, but that makes it automatically searchable, nad one could eg create a list automatically, of stuff that was deprecated between two arbitrary git commits.

i could imagine that not all workarounds/convienence stuff is doable in Lua, and i personally would preffer stuff to stay where it was, as it is most simple to do: bascially, change implementation and add deprecation tags & comments, instead of moving to a new/other file, into a different language.

[knorke]

but about keeping multiple releases as compatible as possible

Yes, but is that even possible?
Games often get incompatible with engine for other reasons than Lua API stuff. There is no backwards compatiblity for changes/bugs in pathing,physics, unit AI etc. all which made games unplayable in the past and forced them to update (http://springrts.com/mantis/view.php?id=3012 , http://springrts.com/mantis/view.php?id=2791, http://springrts.com/mantis/view.php?id=2903 etc)
And since gamedevs have to make a new release for those things anyway, adjusting for some deprecation stuff can be done in the same update - If it is clear what has changed.

the way i described seems like a quite good way of documenting it.

Yes, that would be helpful.
But I see no use for keeping something around just a little longer if it gets removed later anyway: realisticaly no gamedev would continue to use something that is scheduled for soonish removeal.
(so it might be wasted effort)

---
The gundam thing is kind of heartbreaking but that it was "one night after the engine release" does not matter: Some months latter the situation is still the same.

[hoijui]

what you say comes down to:
we have a problem X comprised of subproblems x_1 ... x_n.
it makes no sense resolving sub-problem x_1, becasue there are others left.
makes no sense, casue this way no problem woudl ever be resolved if it can not be resolved in a single go.
also, this is a very easy thing to do right, compared ot the other things that might make stuff incompatible.

when your game is basically compatible between mutliple engine versions, but pathin in half of the versions is broked (at least for your mod), then you can choose one of the engine versions of the other half.
if all these versions are totally incompatible with each other from the start, due to lua stuff, you have no choice, and when your mod(+version) is compatible with one engine version that has borked pathing -> fail

i mean... really?
the discussion is about whether or not to remove a problem.
there is not even a tradeof, or at least nobody mentioned one so far. (which in practise means the same)

[PicassoCT]

Have you thought about Spring "eating" certain LuaMods and Libs and providing them with the installer (for example toolbox) + the tutorial game.

include "SpringUeberLua.lua"



Also a codename for the Release.

[Licho]

Tbh I think that it should go in the other direction -> making sure multi engine download works and making engine updates as small and frequent as possible..for example with at least a weekly update..

This combined with multi engine support (game PICKS what engine version it uses instead being forced!) means you have constant testing, less dramatic breakdowns.

If something breaks, game just wont update its autohosts to latest engine until its fixed.

ZKL already supports this, you just join a battle and it downloads engine after you join.
If SL had similar support we could drop "server-wide" engine version and instead let each game decide its pace and provide instant feedback to engine devs from games that keep the "cutting edge" weekly release.

[hoijui]

hmm good call there Licho.
if we would have engine releases muhc more oftne then breakign changes, that could be an alternative, though.. i would say combining the two things would be even better, even in such a scenario (though the 1 year could be lowered maybe).

[koshi]

I know it's not an issue for ZKL, but multi-version installs are simply not feasible on linux atm and I do not want to spend time on features that don't benefit everybody.

[gajop]

I know it's not an issue for ZKL, but multi-version installs are simply not feasible on linux atm and I do not want to spend time on features that don't benefit everybody.

well the only problem is if you do system wide installs, i don't see why there would be a problem with multi-version installs if you simply installed stuff in $HOME/spring-games f.e

[koshi]

There's no package manager I know that allows that.
From a couple of days ago in #sy: http://pastebin.com/6hbnAJ4E