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.

[wenzeslaus]

...If you could not reasonably ensure that this can be done, we can only make the change with a new version.

Not only we can more than reasonably ensure that project is 'understood', but we can ensure that location is still understood, too. See #3130 and #3131 for examples.

[HuidaeCho]

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?

Reading back Phase 2, so we'll support both (missed it previously) project= and location= until Phase 4 when we'll drop location= eventually. In that case, it would be also great to add a deprecation warning whenever location= is used and advise the use of project=.

My main problem with waiting for v9 is that just renaming location is not in my opinion substantial enough to warrant new major version.

My confusion was from this "just renaming location". If it was just the label without project= support proposed in Phase 2, it would be an issue. However, we actually start supporting the project= parameter along with location= in Phase 2, I think it should be less problematic with the deprecation warning for location=. I think this warning is really needed prior to v9 (even from Python scripts).

[HuidaeCho]

I just thought about a potential confusion between the verb project (as in project data to a coordinate system) vs the new noun project (current location) in the API, but I couldn't find any verb project in the include files.

grep -i '_project[^a-z]' include/grass/*.h include/grass/*/*.h

g.proj currently has proj4= and location=, so proj= shortcut won't work anymore (just a minor annoyance :).

Another source of confusion might be module names *.proj (meant to be verb, I think) vs *.project (verb or noun?), but at this point we don't have any *.project modules. Maybe, I'm overthinking. ;-)

[wenzeslaus]

...In that case, it would be also great to add a deprecation warning whenever location= is used and advise the use of project=.

The warning is there, see #3130.

GRASS GIS generates that warning automatically when the item is in lib/gis/renamed_options.

  ______________________
/ Oh, the things        \
\   GRASS GIS can dooo! /
  ----------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
_\|/__\|/__\|/_ ||     ||  _\|/__\|/_

Grassy the Hungry Cow gives her opinion

[wenzeslaus]

...I couldn't find any verb project in the include files.

I think they are just using proj, but there is also re-project, transform and warp as alternatives if we ever run into some issues.

g.proj currently has proj4= and location=, so proj= shortcut won't work anymore (just a minor annoyance :).

I guess proj4 should be deprecated anyway because PROJ4 strings are deprecated, no?

...at this point we don't have any *.project modules.

If we do, a verb may provide enough context, e.g., g.switch.project.

Context should be enough to distinguish between a project and (re-)project. These overlaps exists even now - db.databases has:

location=name
    Location
    Path for SQLite driver, or connection string for PostgreSQL driver

[cmbarton]

@petrasovaa and others. The version issue I raised boils down to whether a naming change like this warrants a major or minor version number. Looking at GitHub semantic versioning rules, which seem pretty standard, a minor version is for "when you add functionality in a backward compatible manner" and a major version is called for "when you make incompatible API changes". My read on this is that it is an API change that is incompatible with prior GRASS data organization usage. Some of this can be dealt with through software, but not all of it.

So I do not advocate waiting on this change for some other incompatibility to be proposed that would also require a major version change. But that this change itself requires a change, and moving to v.9 sooner rather than later.

Like other potentially incompatible changes, software changes could be instituted in v.8.x to prepare for this--for example going through with the PRs for allowing the argument 'project=' to be accepted as an alternative where 'location=' is now used. But changing the GUI to only show "project" and whatever other changes are decided on, instead of what is presented to users now, should be accompanied by a version change.

[wenzeslaus]

The GUI is not changing to show only "project", "location" is also presented to provide consistency with what users see now.

Specifically, the PR #2993 is keeping (adding) "location" at critical places in GUI, see, e.g., datacatalog/tree.py, line 2220:

- Create new location
+ Create new project (location)

Similarly, PR #3130 does the same for the parameter documentation (lib/gis/parser_standard_options.c):

- Location name
+ Project (location) name

If you identify other places where this should done besides the ones where it is already done in the PRs, please comment on the specific lines in the individual PRs.

[wenzeslaus]

More stories for the history junkies:

r.info documentation says (v8.3):

Information about the map's boundaries, resolution, projection, data type, category number, data base location and mapset, the timestamp and history are put into a table and written to standard output.

Is the missing comma between "data base" and "location" a mistake? Maybe it isn't! Given the "and" between words "location" and "mapset" and the items which follow them, the words "data base location and mapset" seem to be one item in the list which starts with "the map's boundaries" and ends with "history". The words "data base location and mapset" are then two subitems, "data base location" and "mapset" (or "data base mapset").

If this is correct, the words "data base location" refer to one thing, a location where a data base is, not two separate things. In other words, "data base location" refers to a directory where database is. This would fit with the other relicts where location is called database (see #2993 (comment)).

We can theorize that the original v0, v1, or v2 text said:

Information about the map's boundaries, [...,] category number, data base location, the timestamp and history are put into a table and written to standard output.

Addition of mapset to the hierarchy then required adding "and mapset", but the split to "gisbase" and "location" seemed already taken care of by the "data base location" except that an important missing comma was overlooked here.

A strange thing is that it looks like that the word location could have been derived from "data base location" rather than from a reference to an area of interest because simply by splitting the words into "data base location" into "data base" and "location", we get two out of our three current hierarchy levels. What speaks against this theory is that the old documents seems to use exclusively GISDBASE or gisdbase for the top level of the hierarchy while using "database structure" for the whole hierarchy (but not the top level) and (sometimes) "individual database" or "database" for the location. While this does not go directly against the notion that the word "location" is simply a directory as opposed to a geographical area, it goes against the splitting theory because the "data base" from "data base location" is not the name for the top level of the hierarchy.

[cmbarton]

The GUI is not changing to show only "project", "location" is also presented to provide consistency with what users see now.

Specifically, the PR #2993 is keeping (adding) "location" at critical places in GUI, see, e.g., datacatalog/tree.py, line 2220:

- Create new location
+ Create new project (location)

Similarly, PR #3130 does the same for the parameter documentation (lib/gis/parser_standard_options.c):

- Location name
+ Project (location) name

If you identify other places where this should done besides the ones where it is already done in the PRs, please comment on the specific lines in the individual PRs.

This would indeed be helpful in the transition.

[cmbarton]

While thinking about renaming, another legacy term that many users find very confusion is "layer" for vectors. This might go into a different issue. But starting with the file structure names might be a good way to start looking at other confusing legacy terms. Happily, I don't think there are many.

[wenzeslaus]

Renaming Location to Project

by Vaclav Petras

With earliest records going back to 2015, we were discussing how to better name or represent the GRASS location concept. The discussions intensified with redesign of the new startup and data management panel in GUI between 2018 and 2020. A stronger will to rename emerged at the OSGeo Community Sprint in 2022 with renewed discussion and interest at the Prague Community Meeting in June 2023. Most recently, the topic was discussed again at the 2023 Birthday Call and the PSC meeting in August 2023 resulted in the decision to move forward with renaming the location to project.

Need to Rename

While not without controversies and alternative proposals, we are renaming location because:

1. While the system of locations serves well to many users, explaining and understanding the grassdata-location-mapset hierarchy is a continuing problem even after the revolutionary 8.0 release which removed the startup screen.
2. The system of locations has many advantages. Change in that seems to be both not desired by the community and also very costly. However, a better name or representation may bring much benefits with moderate costs.
3. Better representation starts with a better name.
4. The current name, location, has too many other different meanings both in software and in geography. GRASS GIS itself sometimes uses location to refer to path in file system and vector points. Location as something which stores and organizes data is unique to GRASS GIS.
5. We want to emphasize how GRASS GIS is better than other solutions, not merely how it is different. Naming things in a common way seems like a good step towards that.
6. While renaming GISDBASE (or more commonly grassdata) and mapset may have its advantages, location is the crucial part of hierarchy users can’t do without. Focusing on location rather than the other two should bring the greatest benefits.

New Name

We are choosing project as the new name because:

1. Location is the main structure used for organizing data in GRASS GIS. Project is what software packages often use to organize what they work with.
2. The word project should emphasize that this is the level in the hierarchy to focus on. The other two levels might be useful, but this one is crucial.
3. Many people who teach GRASS GIS, describe a location as a project to explain it to new users. (This is also demonstrated by the note below.)
4. While many GIS users perceive projects as merely a state of the GUI, QGIS and especially ArcGIS moved towards storing the visual parts with data.

FAQs

1. My projects do not correspond to locations, so how does the name project make sense? Name of a structure in software does not need to correspond with your work projects. You can have more GRASS projects for one work project or the other way around regardless of the name.
2. Why not rename the location to database? While location is admittedly close to a database in its focus on storing, organizing, and querying data, the word database is already used in GRASS GIS for a different, important purpose, namely to refer to SQL databases storing attributes, temporal dataset metadata, and possibly as backend storing spatial data. Curiously, some places in the current code from before version 3 use the word database to refer to location. Database is also occasionally used for the top-level piece of hierarchy (GISDBASE or grassdata). However, the terms database never got permanently attached to either location or grassdata.
3. Why not rename the location to {an alternative name here}? Project is better than any of the alternatives suggested. Candidate words we considered such as database, workspace, CRS, and projection already refer to a different concept. Using made-up words, grass-related terms, or cow anatomy terms does not help grasping the concept.
4. Why not rename mapset to project? Renaming a mapset to anything is a lower priority than location. The name does not overlap with other meanings and location has a more crucial place in the hierarchy. While the GRASS session is linked to a mapset, it is a mapset within a location. When scripting, mapsets are often ignored, but the location part cannot be.
5. Why not rename GISDBASE to project? While GISDBASE is admittedly the worst name of the three, renaming it would not solve the problem of location which users need to interact with the most.
6. What about GUI workspaces? While the GUI workspace files share a lot in common with projects in other software, the parts they share are state of the GUI. The workspaces in GRASS GIS don’t have the central role project files have in other software.
7. Do I have to change all my data? No, nothing is changing except the name. Importantly, the structure is not changing.
8. Do I have to change all my scripts? No, the renaming is done in a backwards compatible way so at least until the 9.0 release, old parameter names will continue to work.

Example

To demonstrate need for renaming and that the rename is already happening outside of the source code, here is a wording from a 2023 paper by Karlovska, Petrasova, Petras, Landa (emphasis added; besides project, it additionally uses subprojects for mapsets which is not currently planned):

GRASS GIS was conceived from its very beginning as a powerful geospatial computing tool that emphasized data integrity to deliver accurate results. To achieve consistent results when working with data from different sources, GRASS GIS requires the data to be imported into GRASS data storage and reprojected into a common coordinate reference system (CRS) predetermined by the user for each project. Within each project, called location, data are further organized into subprojects, called mapsets, used for managing different subregions or analyses. Additionally, mapsets have distinct processing settings such as computational extent and resolution. The directory with one or more locations is referred to as GRASS database and is typically named grassdata.

Next Steps

Follow the two (out of four) implementation phases described in #3121 (this issue) to finish rename for 8.4. Several PRs are already open covering all crucial areas (tracked in a GitHub project). First next step is merging these PR. Please review or give thumbs up the PRs.

[wenzeslaus]

Does anyone have input on translations? The plan for 8.4.0 (Phase 2) says:

[Renaming] 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.

[neteler]

We need to update the .po/t files for Weblate. Ideally, with a new cronjob.

[echoix]

Wasn't it supposed to be synced by weblate? If not, what does weblate sync?

[neteler]

Wasn't it supposed to be synced by weblate? If not, what does weblate sync?

I remember that @HuidaeCho was doing some manual updates recently (update of message catalog).

[HuidaeCho]

Wasn't it supposed to be synced by weblate? If not, what does weblate sync?

I remember that @HuidaeCho was doing some manual updates recently (update of message catalog).

Weblate only syncs generated PO files and it doesn't generate them as far as I know. Are we ready to generate new PO files for this renaming?