rename readResources, writeResources to parseResources, serializeResources

[samuelstroschein]

Problem

Read and write resources in the config schema imply a filesystem dependency which leads to confusion #395 (reply in thread).

Proposal

Rename readResources and writeResources to parseResources and serializeResources.

Under the hood, resources are parsed and serialized. In every call, I explain inlang's AST architecture that requires the parsing and serialization of resources. Renaming the properties, hopefully, clarifies how inlang works.

• have an auto migration script e.g. everytime someone opens the editor, the editor auto adjusts the config file.

[openscript]

Sounds good. You mention migration. We should create a general plan how to deal with them. In my opinion this is a separate task outside of the scope of this refactoring.

[samuelstroschein]

Yes.

Automatic migration scripts are a different task. I would only start this task once migration scripts exist.

[openscript]

Would you use https://github.com/facebook/jscodeshift for this? I think it's something which should be integrated into the cli and the editor as well as the ide-extension should offer such migrations.

[samuelstroschein]

Maybe.

I am not looking into migration scripts at the moment. Other things like #436 and getting the vscode extension to work in the first place are more important.

[ivanhofer]

Any update on this?

[samuelstroschein]

We could change the name now with the setupConfig function that could have a migration proxy that maps older readResources and writeResources calls to parseResources and serializeResources respectively.

Do you think this is a change that is beneficial and we should do asap?

[ivanhofer]

I would just leave writeResources and readResources as aliases. Just use the new naming schema everywhere.
We can mark them as deprecated and also add tests to our default test suite and warn plugin authors if they use the old properties.
We could also track the usage of this property to see if it still get's used in a few month.

If we agree this needs to be done, then every potential breaking change should be done as early as possible.

[samuelstroschein]

Agree.

(My comment got lost/removed.) We can mark them as deprecate and don't remove them yet. But, I would already use a "migration proxy" that maps readResource and writeResource calls to their respective replacements to easy the removal in a few months.

@inlang/team Should we rename readResources and writeResources to parseResources and serializeResources to clarify a) how inlang works and b) that inlang is not (necessarily) filesystem dependent?

[ivanhofer]

maybe consider getResources and setResources as a name for those functions?

[samuelstroschein]

If we are starting to debate the names of the functions, we can probably leave it as is because it becomes opinionated and focus on other tasks.

I thought serializeResources is a clearer name but tbh the benefit seems small.

[ivanhofer]

read and write is mostly associated with a file system.
parse and serialize sounds a bit to techy and may confuse beginners.
get and set are common terms. At least for me it would fit best.

I wonder what others think?

[ivanhofer]

We probably should also add support for parsing a single Resource within this refactor

[samuelstroschein]

I had a similar thought. Maybe we should leave readResources and writeResources as is then and introduce another API in the near future that is not API compatible.

If you agree, we can probably shelf this discussion for now. What do you think?

[ivanhofer]

Do you think we will have a big overhaul of those two functions in the future? readResources will not really be a breaking change if we just add a new parameter to the function.

[samuelstroschein]

Hmm good question. The object argument pattern enables us to be extremely flexible here. So actually, likely no breaking change coming. If I were to change something now, I would probably get rid of the config argument, now that createPlugin is a thing that has access to the config. This makes consumption of readResources slightly easier. But really minor improvement that is likely not worth a breaking change.

[NilsJacobsen]

Sounds good guys, i also think that reading single resources could become pretty handy in the future. On the other hand I would suggest to always think about that it should stay easy to create plugins. If it will be required to ship 5 functions and pass all the tests it could become hard to quickly develop own plugins.

[samuelstroschein]

Closing because unimportant.