Repo name change

[DavidMStraub]

As discussed here https://github.com/gramps-project/Gramps.js/issues/334, I propose changing the name of this repository from gramps-webapi to grampsweb-api. Comments?

[Nick-Hall]

Do we really need to include the word "gramps" in the repository name?

How about web-api, web-frontend and web-docs?

[emyoulation]

"grampsweb" would be a LOT more search engine friendly than "web". You would get orders of magnitude fewer false positives.

But if the Repository name is changed, the "Gramps Web" fork and product name ought to be renamed to "GrampsWeb" too.

[Nick-Hall]

The organization is "gramps-project" and the repository would be named "web-api". So the address would be "gramps-project/web-api".

[emyoulation]

try googling "web-api site:github.com/"

Google returns 10,700,000 results.

[emyoulation]

googling "grampsweb-api site:github.com/" gives 105 results (after you confirm that you don't mean "gramps web-api site:github.com/"

[Nick-Hall]

Try searching for "gramps-webapi" you will get better results.

[emyoulation]

But that underlines the objection to earlier suggestion to strike 'gramps' from the repository name. The 'gramps' in the repository name and/or the module names reduces the search results to a manageable number.

Do we really need to include the word "gramps" in the repository name? How about web-api, web-frontend and web-docs?

[Nick-Hall]

My suggestion to remove "gramps" from the repository name was because we already have it in the organization name. We don't call our addons repositories "gramps-addons" and "gramps-addons-source".

I'll discuss this with the team.

[emyoulation]

I'll discuss this with the team.

That would be appreciated. It seems likely that this fork will eventually be spun out and become separate from the Desktop GUI. Pieces that scatter to become modules on different servers will benefit from more highly visible pointers back to the core fork.

[DavidMStraub]

I agree with @emyoulation on including "gramps".

In fact, we changed from web-api to gramps-webapi in 2020, see the discussion here https://github.com/gramps-project/gramps-webapi/issues/129#issuecomment-749131225

The reason I propose to change again was just to harmonize between frontend and API and taking into account the fact that we call the two things together "Gramps Web" now, which was not the case back then.

I think among the options

• gramps-project/web-api & gramps-project/web-frontend
• gramps-project/grampsweb-api & gramps-project/grampsweb-frontend

the latter is clearer because there seems to be a lot of confusion among users.

If we had a gramps Github org, I think it would make more sense (gramps/web-api → Gramps Web API), but the "project" in the name makes it less meaningful.

Btw we also don't have gramps-project/desktop 😉

[Nick-Hall]

The reason I propose to change again was just to harmonize between frontend and API and taking into account the fact that we call the two things together "Gramps Web" now, which was not the case back then.

My understanding is that the web API and front-end have a different status. The API is officially supported by Gramps. As such, we will consider how changes in the core design may impact the API. A consequence of this is that the design of the API will need to be approved using the normal Gramps development processes. In practice though, I have never felt the need to get involved.

The front-end is one of possibly many users of the web API. It is not supported by Gramps. I have always considered this as David's project and I do not influence the design. Having said that, we are happy to host the code and promote it as our preferred web option.

This is probably a good time to involve @bmatherly in the discussion. He expect that he has some views on how he would like to see the web project progress.

Btw we also don't have gramps-project/desktop

This has been discussed in the past. The idea was to split "gramps" into "core", "gui" and "cli". At the time I seem to remember that we decided that the extra complexity outweighed any benefits.

We are "gramps-project" on GitHub, but were "gramps" on SourceForge. Although we only have a single product at the moment, this does give us the scope to add a product prefix. I have no real objections to this, although I tend to favour shorter names.

[DavidMStraub]

My understanding is that the web API and front-end have a different status. The API is officially supported by Gramps. As such, we will consider how changes in the core design may impact the API. A consequence of this is that the design of the API will need to be approved using the normal Gramps development processes. In practice though, I have never felt the need to get involved.

Agreed. And as long as the number of developers contributing to the API is fairly low, the development processes (e.g. need for PR review) are necessarily different, but can adapt if this changes.

The front-end is one of possibly many users of the web API.

Agreed.

It is not supported by Gramps. I have always considered this as David's project and I do not influence the design. Having said that, we are happy to host the code and promote it as our preferred web option.

I am not 100% happy with phrasing it like that. I think the API and the frontend are completely different qualitatively, because the API is a Python project that shares code with Gramps, while the frontend is pure Javascript and as such does not depend on Gramps directly (only indirectly via the API). So it's natural that its relation to Gramps is different from a development & governance perspective.

But I don't want to say that it's "my" project that just happens to be hosted by Gramps. For instance, the contributions by the Gramps translator community (which are part of the Gramps open source community) are amazing! And while it's true that there are currently few contributions to the Javascript code except from myself, I am doing my best to change this, and the last 2 months we already had two awesome contributions (hourglass chart + zoom & pan for charts) from a new contributor.

Perhaps a possible way to phrase it is that it's an experimental project by the Gramps open source community, so it's not "supported" in the sense of the Gramps developers endorsing it fully (so users don't expect the same level of quality & feature set as Gramps) but it is "supported" by the open source community around Gramps.

I have no real objections to this, although I tend to favour shorter names.

Ok let's wait 2-3 days in case there are more opinions.

[jralls]

I agree with @DavidMStraub and @emyoulation on this because of git's distributed nature. While it's true that our canonical repositories are hosted at github.com/gramps-project, that identity is lost as soon as a repo is cloned or forked. @Nick-Hall has only 5 repos, all associated with Gramps, in his github account. I have 30 thanks to managing a couple of projects and to contributing pull requests to several others. jralls/grampsweb-api is immediately clear about what project it belongs to; jralls/web-api requires examining the repository contents to find out.

[DavidMStraub]

That is an excellent point, hadn't thought about that.

[bmatherly]

jralls/grampsweb-api is immediately clear about what project it belongs to; jralls/web-api requires examining the repository contents to find out.

As a github user for other projects, I agree strongly with this comment.

My suggestion would be that all repositories in the gramps-project organization should have a "gramps-" prefix.

For example:

• gramps-webapi
• gramps-webfrontend

So I guess that means I am not in favor of renaming this repository, but I am in favor of renaming Gramps.js. Maybe it also makes a case for renaming the original "gramps" repository or even splitting it out into its parts. I am open minded about that. This is one of the painful system architecture decisions that come about as a project is successful.

I like that the organization is called "gramps-project" because it has allowed us to widen our scope and include alternative front ends.

But I don't want to say that it's "my" project that just happens to be hosted by Gramps.

I appreciate that comment. I would like the webapi and webfrontend repositories to be first class citizens. Maybe we could consider that the webfrontend has a different project lead or "primary maintainer" from other repositories?

[DavidMStraub]

For example:

gramps-webapi gramps-webfrontend

So I guess that means I am not in favor of renaming this repository, but I am in favor of renaming Gramps.js

I understand your point, but I am against it, let me explain why.

The application you get when you use the web frontend (originally called Gramps.js) and the Gramps Web API used to not have a name. This confused users, so in this discussion https://github.com/gramps-project/Gramps.js/issues/49 we decided to give a single name to the combined application, and decided to go for "Gramps Web". This already helped a bit, and the documentation for both projects is now hosted at https://www.grampsweb.org/.

However, what I am observing in practive, e.g. when users are reporting issues, is that there is still a lot of confusion caused by the fact that the application lives in two different repositories, and those repositories have names that are (at least in case of the frontend) quite different from the name of the application.

From a development perspective, it makes perfect sense to have the repositories separated, because the development cycle and programming language are different, and because the frontend is only one of many possible uses of the API, so this will certainly never change. But it would help, in my opinion, to unify the naming.

Fortunately, "Gramps Web API" already contains the name "Gramps Web", so that's fine; for Gramps.js, I think we all agree that "Gramps Web Frontend" will be much clearer.

But concerning the repository names, I think gramps-webapi and gramps-webfrontend are not suited because the relation to the "Gramps Web" application is not clear.

An alternative that I would find acceptable would be gramps-web-api and gramps-web-frontend. Perhaps that's a good compromise?

Maybe we could consider that the webfrontend has a different project lead or "primary maintainer" from other repositories?

Yes, that's already the case in practice and I think the way it's working right now is not a problem. When the number of developers increases, we can review the governance.

[Nick-Hall]

Adding a "gramps-" prefix seems like a good idea. It would indicate that these repositories are a main component of Gramps. The support status and governance can be reviewed in the future if required.

I don't mind either Brian's suggestion, or a version with an extra hyphen.

[bmatherly]

I don't mind either Brian's suggestion, or a version with an extra hyphen.

I don't have a preference about the hyphen. The prefix was my main point.

In retrospect, I think, if we were to start from scratch, maybe we would have made these repositories:

• gramps-core
• gramps-desktop
• gramps-cli
• gramps-web-api
• gramps-web-frontend

we decided to give a single name to the combined application, and decided to go for "Gramps Web"

Fortunately, "Gramps Web API" already contains the name "Gramps Web", so that's fine; for Gramps.js, I think we all agree that "Gramps Web Frontend" will be much clearer.

I see your point about users connecting their experience with the correct repository to report to. Another option would be to drop the "frontend" and have "gramps-web" and "gramps-web-api" repositories. I could also support "gramps-web-js".

This discussion also has me wondering... should users be submitting issues to Github or our Mantis tracker? I see the webpage directs people to github. I think that if Gramps Web is a first class citizen in the Gramps Project, then there would be an expectation that it is using all the same support systems and the desktop application. I think that, typically, users would not need to know or care about front/back end. They would submit a ticket to the application and someone else would determine if the problem is in the application, or an upstream library that it depends on.

This is all just food-for-thought from the treasurer. I'm not the one doing the work. I just hope some comments can be helpful. I do want to go on the record to say that I really love that we have both desktop and web interfaces for Gramps and I would love for them to both thrive and grow among our Gramps community. So I tend to prefer conventions and practices that build as much in common as possible between them.

[DavidMStraub]

I see your point about users connecting their experience with the correct repository to report to. Another option would be to drop the "frontend" and have "gramps-web" and "gramps-web-api" repositories. I could also support "gramps-web-js".

Great, we're converging on a decision :slightly_smiling_face: now we just have to pick between gramps-web-frontend, gramps-web, and gramps-web-js for the frontend. I am leaning towards gramps-web and would exclude gramps-web-js.

should users be submitting issues to Github or our Mantis tracker?

I think Github works really well for API & frontend right now, in fact I even think there is a benefit of keeping them separate from the Gramps bug tracker, except the issues that are issues of Gramps itself. Usually when somebody reports an issue via Github that turns out to be an issue in Gramps "core", I tell them to open one in the bug tracker. But in fact that's very rarely the case, because the core is so stable and most issues are introduced by the API or frontend layers. But again this is something that can be reviewed at a later point as the projects evolve.

This is all just food-for-thought from the treasurer. I'm not the one doing the work. I just hope some comments can be helpful. I do want to go on the record to say that I really love that we have both desktop and web interfaces for Gramps and I would love for them to both thrive and grow among our Gramps community. So I tend to prefer conventions and practices that build as much in common as possible between them.

:100:

[emyoulation]

This 1st-class concept is important.

People are already developing features that are not related to the GrampsWeb GUI or the server OS support for this fork.

There should be some mechanism for those new functionalities to flow back into the core... so that the forks do not diverge so far that they need to stage an uprising.

We may have missed promoting a fork to 1st-class. The Narrative Web has effectively been a GUI fork for static data for a long time. And another thread has Betty' creator wanting to achieve dual-citizenship. (Perhaps both of these could use the WebSync functionality to feed their engines?)

Eventually, we can expect a VR GUI adventurer to want to use the Gramps core.

[DavidMStraub]

@emyoulation please do not call this "fork". It is not a fork! So I also don't understand your concern. There is no divergence.

Yes, we need to incorporate as much as code as possible in the core, but the reason that is not happening too much is mostly related to the different release cadence - it does not make sense to add a new feature to Gramps Web that needs to wait for a new minor Gramps release; the last one was more than 4 years ago.

[emyoulation]

please do not call this "fork". It is not a fork! So I also don't understand your concern. There is no divergence.

My apologies. But there do seem to be things that are not compatible (yet). Like the Tasks and Search engine mentioned in https://gramps.discourse.group/t/using-groups/as-task-app/4022 . Likewise, the OCR capability is likely to create some envy in Desktop community.

Although, I cannot find the reference immediately, you had a post about some contributors adding new functionalities that don't exist in the Desktop version.

Those are expected in the GUI. Your graphs are more elegant and finely rendered than in the desktop's Charts views. (That is praise, not criticism about compatibility.)

[emyoulation]

it does not make sense to add a new feature to Gramps Web that needs to wait for a new minor Gramps release; the last one was more than 4 years ago.

The Gramps Desktop release is 4 years behind the Master branch.

But maybe core features introduced to Gramps Web should already have a PR or Commit to the Master branch? Those do not suffer from the same lag.

So Desktop will have a chance to catch up compatibility with Gramps Web?

[DavidMStraub]

I plan to rename to gramps-project/gramps-web-api tomorrow.

[Nick-Hall]

OK. Let me know if you have any problems.