Rename location to project

[wenzeslaus]

We are renaming location to project. The goal is to replace the term location by the term project in user-facing strings, texts, and APIs. The rename was decided by community consensus which is a result of more than 5 years of discussion.

Phase 1

Minimal changes needed to allow all people to contribute changes and start making changes in their own materials.

• wxGUI: Minimal changes to rename location to project #2993

Phase 2

Things which need to happen to rename location to project. This needs to happen before 8.4.0. This issue will be closed as completed when this phase is finished.

• Rename all in GUI user-visible strings.
• This will require the new strings to be translated. We can consider releasing instructions on how these translations should happen. While location and mapset should not be translated, project can be. If we decide to include things like "new project (location)" we may need to give instructions about that, esp. because we will eventually remove the "(location)" part.
• Rename tool parameters (aka module options aka CLI API)
  • We have a system in place for renames in parser (introduced with renames for 7.0) and we can introduce an additional parameter in case the automated system is not enough.
  • Example: r.proj location=name will become r.proj project=name but r.proj location=name will continue to work.
  • Identified tools with custom location parameter: t.vect/rast.import (t.vect.import: rename location parameter to project #3610), g.proj (g.proj: rename location parameter to project #3573), r.in.gdal (r.in.gdal: rename option location to project #3575), v.in.ogr (v.in.ogr: rename option location to project #3576), v.in.lidar, i.target
  • Identified tools with G_OPT_M_LOCATION standard option: g.mapset, r.proj, v.proj, g.download.location, i.ortho.elev, i.ortho.target, g.gui.image2target
  • Identified tools with word location with different meaning: db.databases (location=path to database or connection string), i.ortho.target (mapset_location?)
  • Needs to include changes in code which calls these tools (e.g. calls from GUI)
  • See also wxGUI: Minimal changes to rename location to project #2993 (comment)
• Python API
  • It is little hard to tell what is the extent of changes needed. grep -IrnE location jupyter/ pygrass/ script/ temporal/ gives a lot of results, but places where it actually matters seem to be much more scarce.
  • Changes definitively needed in grass.script.setup.init, create_location, create_environment.
  • Compatibility in general: In Python, a new parameter can be safely introduced without breaking the API. The location parameter may move to the end of the parameter list and the new project can take its place in front where the location parameter was originally.
  • Compatibility for grass.script.setup.init: Typical call looks like init(".../path/...") or init(".../path", "name", "name"), so the rename might not be even noticeable and no change to user code would be needed in this case.
• Update documentation. While most of the documentation would be best updated together with the relevant tools or functions, there is also a lot of documentations not directly linked to a specific piece of code. This will need to be be reviewed and updated. See doc: continue renaming location to project in documentation #3570.

Phase 3

Things to consider, but are not necessary for 8.4.0, for completing this issue, or in general. This is included only for context.

• Rename to project in C API. New names can be added in a backwards compatible way. The rename will be mostly happening from G_database_* to G_project_* (and only partially from location), so it does not seem to be time-sensitive. See also wxGUI: Minimal changes to rename location to project #2993 (comment) and wxGUI: Minimal changes to rename location to project #2993 (comment).
• De-emphasize GISDBASE as its own thing from user perspective. Gisdbase (GISDBASE, gisdbase) was never really readable. Presenting it as simply the directory when one or more projects (locations) are might be sufficient. The directory can still be treated in a special way as it is now, e.g., in command line, it is easier to switch to mapset in another project (location) in the same gisdbase than it is in another gisdbase. For example, grass.script.setup.init calls the parameter path and not gisdbase.
• Allow users to use "path to mapset" in more places in addition to specifying it as three items. There is no reason for path to mapset to be always split into three parameters. For example, grass.script.setup.init has only one mandatory parameter called path. If you write init(path), the path it is used as path to mapset, but you write init(database, location, mapset), the path becomes the database directory and the other two are location (project) and mapset. More places could support this logic, e.g., GUI can have a new ability to open mapsets (there is not File > Open mapset now), r.proj and g.mapset can have the same "path or path+name+name" behavior as grass.script.setup.init.
• Allow users to specify just the path to a project (location) and default to PERMANENT mapset. The PERMANENT mapset is currently created by default. This would also use it by default, e.g., when user in GUI navigates to a project directory with (currently non-existent) File > Open mapset.
• Don't ask about overwriting GUI workspace file when it is the file which is open. (This is the common behavior and would fit with per-mapset GUI workspace files.)
• wxGUI: Make GUI workspace part of mapset #3113
• Allow more than one workspace to be stored in a mapset.
• Auto-save workspace often and be able to basically "restore the last [GUI] session".
• Remove location from code where it is used in variable names, comments and other things which are limited just to that piece of code.

Phase 4

Things which can be done only for or after the 9.0 release. This is included only for context.

• Remove legacy location parameters and functions with that name which were kept for backward compatibility in Phase 3.
• Remove mentions of location from user-visible strings and documentation except for one or two places where the old naming is explained. For example, when the text says "create a new project (location)" we would remove "(location)" and leave only "create a new project". This will require to update translations.
• Remove location from backend. This is especially LOCATION_NAME variable in the session file (rcfile) managed by g.gisenv and directly. The session file is somewhat backend-ish, but it was used as a frontend for a long time, so this can be done only with a major release. Ideally, we would add features to replace all direct use cases of the session file before 9.0 so that this change would not effect anyone. Alternatively, we do the renames of these variable in a backwards compatible way, e.g., we use PROJECT_NAME but continue to support LOCATION_NAME.

Here are some pointers to the discussions which lead to this decision:

• PSC Meeting 2023-08-11
• wxGUI: Minimal changes to rename location to project #2993
• GRASS GIS at OSGeo Community Sprint 2022
• Proposals for a new GRASS GIS startup mechanism (2018-2020)
• grass-dev: a proposal to rename "location" (2018)
• grass-dev: Brainstorm about new GRASS GIS startup (2018)
• grass-dev: New splash screen for GRASS GIS 7? (2015)

[hellik]

Things which need to happen to rename location to mapset.

Is it that way?

[wenzeslaus]

Is it that way?

That would certainly be an interesting turn. Phase 2 description fixed.

[cmbarton]

Here are a couple of roadmap ideas.

1. This is a drastic enough change for how users interact with GRASS, even if backward compatibility, that it should be done only with the launch of a new version 9. We would need to have considerable warning to users and this would give us the opportunity to do so.
2. Given that there is an opportunity to rethink the GRASS file structure and how it is represented to users, described in the detailed intro to this issue, I think it makes sense to consider a slight further change. This is relevant for the Phase 3 part. We should consider renaming mapsets to workspaces, and then the workspace description file described for Phase 3 would simply be a workspace configuration. Save all workspace *.gwx files within the workspace (=mapset) where they are created. As suggested in the Phase 3 plan, the last used workspace configuration in each workspace would be the initial default when a workspace is entered.

[petrasovaa]

1. This is a drastic enough change for how users interact with GRASS, even if backward compatibility, that it should be done only with the launch of a new version 9. We would need to have considerable warning to users and this would give us the opportunity to do so.

Version 9 is still a bit far, while I think we are ready to proceed with this now. I wouldn't consider it drastic either, there is no change in behavior. Changing naming in backwards compatible way for 8.4 doesn't break any semantic versioning rules.

[cmbarton]

Note that I am in favor of this plan and think the phases proposed are a good plan. It is also good that there are ways to do this that will ensure backward compatibility from a software engineering perspective. But it will not be backward compatible from a semantic perspective (in the original usage of the term). It won't be backward compatible with 40 years of manuals, documentation. papers, presentations, tutorials, etc.

This is not a reason to not move ahead with renaming and rethinking the GRASS file structure. But it is a reason to make this a new version.

Developers and users need to be informed of this before it is done in order to plan accordingly. While there have periodically been discussions, this new plan has not yet been announced to the dev community nor to the user community. It should not be 'talked to death' of course. So it is good that there is now a concrete plan to consider, and modify if needed. Giving it a set timeline could help keep it from dragging out.

But IMHO, it is still a significant enough change that it requires a new version.

[hellik]

Developers and users need to be informed of this before it is done in order to plan accordingly.

Good point.

[wenzeslaus]

As for having this in version 8.4 or 9, I don't think v9 should be done for the PRs which are currently open. The concept is not changing, only the name is changing and the phased approach introduces the word project without removing the word location. The phases 1 and 2 are introducing things in a backwards compatible way and the word location is mentioned alongside project at crucial places. Phase 4 will remove all visible occurrences of the word location so that the rename to project is completed for the 9.0.0 release.

[wenzeslaus]

...this new plan has not yet been announced to the dev community nor to the user community.

Is grass-dev and grass-user what you have in mind? I will be working on a post to a mailing list, just not sure if one or both.

[cmbarton]

As for having this in version 8.4 or 9, I don't think v9 should be done for the PRs which are currently open. The concept is not changing, only the name is changing and the phased approach introduces the word project without removing the word location. The phases 1 and 2 are introducing things in a backwards compatible way and the word location is mentioned alongside project at crucial places. Phase 4 will remove all visible occurrences of the word location so that the rename to project is completed for the 9.0.0 release.

This all implies that terms employed by users are not important and only the terms used within software. I've always believed otherwise--that the user experience is as important as the software architecture. If you use the term "project" as an argument in a command that only 'understands' the term "location". The software will raise an error. This, of course, is the reason for some of the proposed software changes in the plan: to ensure that the term "project" when used in GRASS modules (including those underlying the GUI) are 'understood' by the software as referring to the data structures previously called a "location". If you could not reasonably ensure that this can be done, we can only make the change with a new version. This happened at the GRASS 6/7 version change for the arguments used in r. watershed. It involved important improvements to that module, but it had significant impacts for complex modeling code that my team was developing and deploying. We had to rewrite some of the code and then go back and change the information documenting both older and updated code to clearly indicate which GRASS version could be used. But it was clear that this happened at a version update.

All the usage in all the information and knowledge base of GRASS users for 40 years has used the terms GISDatabase, location, and mapset to refer to GRASS data structures. There is no way to update nearly any of that information. This is why I am saying it is not backward compatible. In this case, it is not only the software that has to be changed, but how people understand and refer to GRASS operation.

This all should have been done a long time ago. The version 5/6 or 6/7 updates would have been good places, but didn't happen. So I'm glad that you are working on this now. I just believe that it requires a version change. That also gives us the option of considering additional components of a more comprehensive review of the file structure that is also implied in the proposal. I may be the only one that feels that way. If so, that's OK. But it should be seriously considered.

[HuidaeCho]

I may be the only one that feels that way. If so, that's OK. But it should be seriously considered.

@cmbarton I feel the same way. Even though it'll be only the label that changes until phase 4, it can be confusing to new and existing users as well until v9 because

In this case, it is not only the software that has to be changed, but how people understand and refer to GRASS operation.

[petrasovaa]

@cmbarton I feel the same way. Even though it'll be only the label that changes until phase 4, it can be confusing to new and existing users as well until v9 because

I am not sure whether you don't assign version 9 some magic powers :) Waiting for v9 is going to delay the somewhat inevitable confusion, but I don't think it's going to prevent it. What I don't understand is, do you suggest to delay this until we are ready for v9 (with other changes that may require breaking backwards compatibility), which can be couple years, or are you suggesting to release v9 soon, like next year? How would the transitional period look like? Or no transitional period needed, since it's a major version?

My main problem with waiting for v9 is that just renaming location is not in my opinion substantial enough to warrant new major version. If we decide this absolutely needs to be changed only in v9, than with the current speed of releases it will take 5 years. We need to have more substantial changes to make the new major release and we need time to develop them. That obviously brings some practical development issues like these PRs will be open forever since we can't merge them to main branch which is used for minor releases. Moreover, since the rename is trying to make GRASS more user-friendly and easier to teach to new users, delaying this is problematic.

Starting the backwards compatible changes now would give us time to think, experiment and develop the idea further, e.g., what to do with workspaces and down the line we may find the need to introduce larger changes and at that point v9 would be appropriate.

Lastly, current software is being changed increasingly often. Users are getting used to it.