Renaming "Project" to "Repository" and "GRepository"

[Patrick Hiesel]

Hi,

we discussed on a recent hackathon, that we want to rename "project" to "repository" in Gerrit and from what I recall there was consensus about that.

We looked into this a bit more and wanted to discuss a proposal before heading into the implementation.

Motivation

Users know Git. In Git you have repositories. Gerrit calls these projects and it is not immediately clear that repo == project. Renaming will lower the entry barrier to Gerrit.

Option 1: Rename "project" to "repository" in the UI and docs only.

This is the bare minimum, it includes renaming /projects/ to /repositories/ in the API (of course keeping the old schema around to not break callers). The UI is already moving to the term "repo". It leaves the code with "project".

Option 2: Rename "project" to "repository" in UI, docs and code.

In this option, we would rename all things that carry "project" in their name to "repository". That poses two questions:

a) How do we distinguish an object called "RepositoryState" (the successor of ProjectState) from JGit's RepositoryState.

A potential solution to that is naming types GRepositorySomething. Where the "G" indicates that it belongs to Gerrit, not JGit. This would only cover types, not methods, since with methods it is sufficiently clear that they are provided by Gerrit.

Example for a method: permissionBackend.user(user).repository(repo);

b) Should we stick to the long (Repository / Repositories) or short name (repo / repos)?

The long name is cumbersome to type but lowers the entry barrier for new developers since going with abbreviations that are specific to the code base increases the time a new developer needs to ramp up.

Option 2 seems favorable because it leaves behind a consistent state, even though it is more work.

Happy to hear your thoughts!

Thanks,

Patrick

[Matthew Webber]

A potential solution to that is naming types GRepositorySomething. Where the "G" indicates that it belongs to Gerrit, not JGit.

G could also stand for Git, so maybe use the longer GerritRepositorySomething?

[Saša Živkov]

On Wed, Jan 24, 2018 at 11:24 AM, 'Patrick Hiesel' via Repo and Gerrit Discussion <repo-d...@googlegroups.com> wrote:

Hi,

we discussed on a recent hackathon, that we want to rename "project" to "repository" in Gerrit and from what I recall there was consensus about that.

We looked into this a bit more and wanted to discuss a proposal before heading into the implementation.

Motivation

Users know Git. In Git you have repositories. Gerrit calls these projects and it is not immediately clear that repo == project. Renaming will lower the entry barrier to Gerrit.

Option 1: Rename "project" to "repository" in the UI and docs only.

This is the bare minimum, it includes renaming /projects/ to /repositories/ in the API (of course keeping the old schema around to not break callers). The UI is already moving to the term "repo". It leaves the code with "project".

Option 2: Rename "project" to "repository" in UI, docs and code.

In this option, we would rename all things that carry "project" in their name to "repository". That poses two questions:

a) How do we distinguish an object called "RepositoryState" (the successor of ProjectState) from JGit's RepositoryState.

A potential solution to that is naming types GRepositorySomething. Where the "G" indicates that it belongs to Gerrit, not JGit.

IMHO, a name should indicate what the type is, rather than where it belongs to.

In that sense GitRepositorySomething would also be a possible candidate?

 

This would only cover types, not methods, since with methods it is sufficiently clear that they are provided by Gerrit.

Example for a method: permissionBackend.user(user).repository(repo);

b) Should we stick to the long (Repository / Repositories) or short name (repo / repos)?

The long name is cumbersome to type but lowers the entry barrier for new developers since going with abbreviations that are specific to the code base increases the time a new developer needs to ramp up.

Option 2 seems favorable because it leaves behind a consistent state, even though it is more work.

+1 for option 2 :-)

 

Happy to hear your thoughts!

Thanks,

Patrick

--
--
To unsubscribe, email repo-discuss+unsubscribe@googlegroups.com
More info at http://groups.google.com/group/repo-discuss?hl=en

---
You received this message because you are subscribed to the Google Groups "Repo and Gerrit Discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to repo-discuss+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Dave Borowitz]

On Wed, Jan 24, 2018 at 5:24 AM, 'Patrick Hiesel' via Repo and Gerrit Discussion <repo-d...@googlegroups.com> wrote:

Hi,

we discussed on a recent hackathon, that we want to rename "project" to "repository" in Gerrit and from what I recall there was consensus about that.

You are thinking of https://groups.google.com/d/topic/repo-discuss/Rdn6Nk_Txwk/discussion

 

We looked into this a bit more and wanted to discuss a proposal before heading into the implementation.

Motivation

Users know Git. In Git you have repositories. Gerrit calls these projects and it is not immediately clear that repo == project. Renaming will lower the entry barrier to Gerrit.

Option 1: Rename "project" to "repository" in the UI and docs only.

This is the bare minimum, it includes renaming /projects/ to /repositories/ in the API (of course keeping the old schema around to not break callers). The UI is already moving to the term "repo". It leaves the code with "project".

Option 2: Rename "project" to "repository" in UI, docs and code.

In this option, we would rename all things that carry "project" in their name to "repository". That poses two questions:

+1

 

a) How do we distinguish an object called "RepositoryState" (the successor of ProjectState) from JGit's RepositoryState.

A potential solution to that is naming types GRepositorySomething. Where the "G" indicates that it belongs to Gerrit, not JGit. This would only cover types, not methods, since with methods it is sufficiently clear that they are provided by Gerrit.

Example for a method: permissionBackend.user(user).repository(repo);

b) Should we stick to the long (Repository / Repositories) or short name (repo / repos)?

The long name is cumbersome to type but lowers the entry barrier for new developers since going with abbreviations that are specific to the code base increases the time a new developer needs to ramp up.

I'm not sure I understand your objection. Are you saying that a new developer who sees the term "repo" in code/docs/whatever will not understand that "repo" is short for "repository"? If so, sorry, I don't buy it, that just doesn't seem realistic.

 

Option 2 seems favorable because it leaves behind a consistent state, even though it is more work.

Happy to hear your thoughts!

Thanks,

Patrick

--

[Martin Fick]

On Wednesday, January 24, 2018 09:04:12 AM 'Dave Borowitz'

via Repo and Gerrit Discussion wrote:
> On Wed, Jan 24, 2018 at 5:24 AM, 'Patrick Hiesel' via Repo

> I'm not sure I understand your objection. Are you saying
> that a new developer who sees the term "repo" in
> code/docs/whatever will not understand that "repo" is
> short for "repository"? If so, sorry, I don't buy it,
> that just doesn't seem realistic.

Perhaps not, however "repo" does have the downside of
clashing with the infamous "repo" tool which many Gerrit
devs do have to live with, and likely will for another
decade,

-Martin

--
The Qualcomm Innovation Center, Inc. is a member of Code
Aurora Forum, hosted by The Linux Foundation

[Martin Fick]

On Wednesday, January 24, 2018 11:24:17 AM 'Patrick Hiesel'

via Repo and Gerrit Discussion wrote:
>

> *Option 2: *Rename "project" to "repository" in UI, docs

> and code. In this option, we would rename all things that
> carry "project" in their name to "repository". That poses
> two questions:

I favor this option, but would not be upset with option 1.

> a) How do we distinguish an object called
> "RepositoryState" (the successor of ProjectState) from
> JGit's RepositoryState.

I use the jgit Repository and the Gerrit Project and
ProjectState objects all the time. I have never used the
jgit RepositoryState object. Is this something used more
often in a modern Gerrit? In the code, I would be more
worried about the conflict with both Jgit and Gerrit's
Repository (if we rename the Project object to Repository),
but I don't know how much Project is used in the current
code base. The Project object was removed a long time ago
from the DB, does it serve much of a purposed any more? It
is embedded in the Branch.NameKey which perhaps should be
renamed to Ref.NameKey? Although I typically think of a
Branch.NameKey as something that I can upload changes to, I
would not put a tag (which is a ref) in there, and if it
were called Ref.NameKey, I might put a tag in there.

I think "Repo" with a capital is likely the best name for
the old Project object in the code. But we could call it a
GRepo if we wanted, not to show that it comes from Gerrit,
but because it has different attributes than a jgit
Repository. We could call it a MetaRepo, or MRepo since if
is a git repository with a refs/meta/config branch (the
current primary distinguishing difference between a plain git
repository and a Gerrit one. But I would think of
permission only projects, All-Projects, and All-Users as
meta repos. And a GRepo would also capture the
refs/meta/config difference and any other Gerrit differences.
So I think GRepo is good. As for clashing with "Git", I
don't think we have Git in our codebase, we have jgit, so
I'm not too worried about that.

What do we do about All-Projects though?

[Dave Borowitz]

On Wed, Jan 24, 2018 at 9:32 AM, Martin Fick <mf...@codeaurora.org> wrote:

On Wednesday, January 24, 2018 09:04:12 AM 'Dave Borowitz'
via Repo and Gerrit Discussion wrote:
> On Wed, Jan 24, 2018 at 5:24 AM, 'Patrick Hiesel' via Repo
> I'm not sure I understand your objection. Are you saying
> that a new developer who sees the term "repo" in
> code/docs/whatever will not understand that "repo" is
> short for "repository"? If so, sorry, I don't buy it,
> that just doesn't seem realistic.

Perhaps not, however "repo" does have the downside of
clashing with the infamous "repo" tool which many Gerrit
devs do have to live with, and likely will for another
decade,

Sure, and for that reason I think the Gerrit documentation should stick with "repository", but within the Gerrit source code I don't see the problem with "repo".

[Dave Borowitz]

Thanks for the suggestions, Martin.

On Wed, Jan 24, 2018 at 9:50 AM, Martin Fick <mf...@codeaurora.org> wrote:

On Wednesday, January 24, 2018 11:24:17 AM 'Patrick Hiesel'
via Repo and Gerrit Discussion wrote:
>
> *Option 2: *Rename "project" to "repository" in UI, docs
> and code. In this option, we would rename all things that
> carry "project" in their name to "repository". That poses
> two questions:

I favor this option, but would not be upset with option 1.

> a) How do we distinguish an object called
> "RepositoryState" (the successor of ProjectState) from
> JGit's RepositoryState.

I use the jgit Repository and the Gerrit Project and
ProjectState objects  all the time.  I have never used the
jgit RepositoryState object.  Is this something used more
often in a modern Gerrit?

No, I too have never used RepositoryState :)

 

In the code, I would be more
worried about the conflict with both Jgit and Gerrit's
Repository (if we rename the Project object to Repository),
but I don't know how much Project is used in the current
code base.  The Project object was removed a long time ago
from the DB, does it serve much of a purposed any more?

Good point. ISTM all the fields could be moved to either ProjectConfig or ProjectState (using current names, of course). Edwin is also thinking of something similar for Account/AccountGroup.

 

It is embedded in the Branch.NameKey which perhaps should be
renamed to Ref.NameKey?  Although I typically think of a
Branch.NameKey as something that I can upload changes to, I
would not put a tag (which is a ref) in there, and if it
were called Ref.NameKey, I might put a tag in there.

I'd respectfully like to table this discussion since we already have our hands full with the project->repo conversion :)

 

I think "Repo" with a capital is likely the best name for
the old Project object in the code.

+1

 

But we could call it a
GRepo if we wanted, not to show that it comes from Gerrit,
but because it has different attributes than a jgit
Repository.

-0.5

 

We could call it a MetaRepo, or MRepo since if
is a git repository with a refs/meta/config branch (the
current primary distinguishing difference between a plain git
repository and a Gerrit one.

-1. To me, "meta repo" means "repo that contains only metadata and no real (i.e. code) data".

 

But I would think of
permission only projects, All-Projects, and All-Users as
meta repos.

I think this is you agreeing with me.

 

And a GRepo would also capture the
refs/meta/config difference and any other Gerrit differences.
So I think GRepo is good.  As for clashing with "Git", I
don't think we have Git in our codebase, we have jgit, so
I'm not too worried about that.

What do we do about All-Projects though?

It's already somewhat mutable in that the name can be configured via setting gerrit.allProjects. Of course, you should really not change that in a non-empty site. A migration tool would be a bit of work but feasible: set the config option, rename the repo, update parent pointers in all other repos, reindex all affected changes.

 

-Martin

--
The Qualcomm Innovation Center, Inc. is a member of Code
Aurora Forum, hosted by The Linux Foundation

[Martin Fick]

On Wednesday, January 24, 2018 10:07:54 AM Dave Borowitz
wrote:

> Thanks for the suggestions, Martin.
>
> On Wed, Jan 24, 2018 at 9:50 AM, Martin Fick
<mf...@codeaurora.org> wrote:
> > In the code, I would be more
> > worried about the conflict with both Jgit and Gerrit's
> > Repository (if we rename the Project object to
> > Repository), but I don't know how much Project is used
> > in the current code base. The Project object was
> > removed a long time ago from the DB, does it serve much
> > of a purposed any more?
> Good point. ISTM all the fields could be moved to either
> ProjectConfig or ProjectState (using current names, of
> course). Edwin is also thinking of something similar for
> Account/AccountGroup.

Sounds good

> > It is embedded in the Branch.NameKey which perhaps
> > should be renamed to Ref.NameKey? Although I typically
> > think of a Branch.NameKey as something that I can
> > upload changes to, I would not put a tag (which is a
> > ref) in there, and if it were called Ref.NameKey, I
> > might put a tag in there.
> I'd respectfully like to table this discussion since we
> already have our hands full with the project->repo
> conversion :)

Of course, and I should point out that Project.NameKey is
actually what is used in the Branch,NameKey (not Project),
and it really is just a string of the repository name, so
Project.NameKey has little relation to the Project Object
anymore. Do we have another "key" object type, like the
GWTORM Keys to replace these with now that we are moving
away from reviewdb? The GWTORM keys provided a lot of value
as keys (typically immutable, well written equals,
composable ...) even without the db, they are great to use
as keys in maps and caches. So while I think we should
table the rename of Branch.NameKey, what would we put in
there if we rename Project?

> > What do we do about All-Projects though?
>
> It's already somewhat mutable in that the name can be
> configured via setting gerrit.allProjects.

Very good point, that seems to address my biggest concern,

[Patrick Hiesel]

First of all let me say: Thank you. This is exactly the discussion I was hoping for so that we can sort this out cleanly before jumping into the implementation :)

Personally I don't see a problem in abbreviating Repository with Repo in code, also not for new developers, but I did want to bring it up. Also because it was part of some prior internal discussions.

I do agree that we shouldn't call it "Repository" in code for the potential clash with JGit that would leave us with calling one of the two with it's fully-qualified package name. That does of course not say that we can't do this in the docs/UI.

I have never used JGit's RepositoryState but wanted to bring up potential name clashes by calling out an example.

Let me see if I can summarize the current state of the discussion (this is not to draw any conclusion yet):

- Rename "Project" to "Repo" in all types, methods and interfaces

- Renaming "Project" to "Repository" in docs, UI and API

- Mid-term remove the "Project" entity and move it's logic into RepoState and other places. Short-term leave this as-is to not clash with JGit

- (?) Rename project.config to repository.config

- Long-term rename Branch to Ref in code (and reference in UI, docs, API)

- Rename the default of All-Project to All-Repositories. Since it is configurable, people can stick with the old name if desired.

[Edwin Kempin]

On Wed, Jan 24, 2018 at 4:25 PM, Martin Fick <mf...@codeaurora.org> wrote:

On Wednesday, January 24, 2018 10:07:54 AM Dave Borowitz
wrote:
> Thanks for the suggestions, Martin.
>
> On Wed, Jan 24, 2018 at 9:50 AM, Martin Fick
<mf...@codeaurora.org> wrote:
> > In the code, I would be more
> > worried about the conflict with both Jgit and Gerrit's
> > Repository (if we rename the Project object to
> > Repository), but I don't know how much Project is used
> > in the current code base.  The Project object was
> > removed a long time ago from the DB, does it serve much
> > of a purposed any more?
> Good point. ISTM all the fields could be moved to either
> ProjectConfig or ProjectState (using current names, of
> course). Edwin is also thinking of something similar for
> Account/AccountGroup.

Sounds good

As a first step I was only thinking about making Account immutable.

Merging Account into AccountState would be nice, but in the short term it's unlikely that I have time to look into this.

 

[Martin Fick]

On Wednesday, January 24, 2018 04:29:37 PM Patrick Hiesel
wrote:

>
> Let me see if I can summarize the current state of the
> discussion (this is not to draw any conclusion yet):
> - Rename "Project" to "Repo" in all types, methods and
> interfaces - Renaming "Project" to "Repository" in docs,
> UI and API - Mid-term remove the "Project" entity and
> move it's logic into RepoState and other places.
> Short-term leave this as-is to not clash with JGit - (?)
> Rename project.config to repository.config - Long-term
> rename Branch to Ref in code (and reference in UI, docs,
> API) - Rename the default of All-Project to

I don't think there was any agreement on this, since it has
downsides. The agreement was to table this discussion for
later. :)

> All-Repositories. Since it is configurable, people can
> stick with the old name if desired.

We don't yet have a proposal for what to do with the
Project.NameKeys all over, including in the Branch.NameKey?

[Dave Borowitz]

On Wed, Jan 24, 2018 at 10:29 AM, Patrick Hiesel <hie...@google.com> wrote:

First of all let me say: Thank you. This is exactly the discussion I was hoping for so that we can sort this out cleanly before jumping into the implementation :)

Personally I don't see a problem in abbreviating Repository with Repo in code, also not for new developers, but I did want to bring it up. Also because it was part of some prior internal discussions.

I do agree that we shouldn't call it "Repository" in code for the potential clash with JGit that would leave us with calling one of the two with it's fully-qualified package name. That does of course not say that we can't do this in the docs/UI.

I have never used JGit's RepositoryState but wanted to bring up potential name clashes by calling out an example.

Let me see if I can summarize the current state of the discussion (this is not to draw any conclusion yet):

- Rename "Project" to "Repo" in all types, methods and interfaces

- Renaming "Project" to "Repository" in docs, UI and API

I don't think we've settled whether it should be /repositories/ or /repos/ in the REST and extension APIs.

Also, at least for googlesource.com, we will need to support both /repos/ and /projects/ for a period of time, both to support incremental rollouts and to give our callers a chance to migrate their tooling.

 

- Mid-term remove the "Project" entity and move it's logic into RepoState and other places. Short-term leave this as-is to not clash with JGit

- (?) Rename project.config to repository.config

Ugh, yeah. Not immediately necessary.

 

- Long-term rename Branch to Ref in code (and reference in UI, docs, API)

- Rename the default of All-Project to All-Repositories. Since it is configurable, people can stick with the old name if desired.

Optional: write a migration tool.

[Dave Borowitz]

On Wed, Jan 24, 2018 at 10:35 AM, Edwin Kempin <eke...@google.com> wrote:

On Wed, Jan 24, 2018 at 4:25 PM, Martin Fick <mf...@codeaurora.org> wrote:

On Wednesday, January 24, 2018 10:07:54 AM Dave Borowitz
wrote:
> Thanks for the suggestions, Martin.
>
> On Wed, Jan 24, 2018 at 9:50 AM, Martin Fick
<mf...@codeaurora.org> wrote:
> > In the code, I would be more
> > worried about the conflict with both Jgit and Gerrit's
> > Repository (if we rename the Project object to
> > Repository), but I don't know how much Project is used
> > in the current code base.  The Project object was
> > removed a long time ago from the DB, does it serve much
> > of a purposed any more?
> Good point. ISTM all the fields could be moved to either
> ProjectConfig or ProjectState (using current names, of
> course). Edwin is also thinking of something similar for
> Account/AccountGroup.

Sounds good

As a first step I was only thinking about making Account immutable.

Merging Account into AccountState would be nice, but in the short term it's unlikely that I have time to look into this.

Not trying to put pressure on you to fix this immediately, just wanted to point out that it's exactly the same issue, so we should use the same approach in all 3 cases.

[Olivier Croquette]

On Wednesday, January 24, 2018 at 11:24:23 AM UTC+1, Patrick Hiesel wrote:

we discussed on a recent hackathon, that we want to rename "project" to "repository" in Gerrit and from what I recall there was consensus about that.

Just my 2ct: from my user and admin perspective, it's a very good idea. Not only "repository" is straightforward to understand for existing Git users, "Project" is a very overloaded term that is used very differently in the various applications.

[Jonathan Nieder]

Patrick Hiesel wrote:

I have never used JGit's RepositoryState but wanted to bring up potential name clashes by calling out an example.

 

By the way, with my jgit contributor hat on: the RepositoryState enum name is not self explanatory, so I wouldn't be broken hearted if it were deprecated and replaced with something more specific.

That doesn't technically affect this since RepositoryState and RepoState are different identifiers, but it might be nice since then RepoState and RepositoryState would clash less in people's heads too.

Thanks,

Jonathan

[Matthias Sohn]

On Thu, Jan 25, 2018 at 7:30 PM, 'Jonathan Nieder' via Repo and Gerrit Discussion <repo-d...@googlegroups.com> wrote:

Patrick Hiesel wrote:

I have never used JGit's RepositoryState but wanted to bring up potential name clashes by calling out an example.

 

By the way, with my jgit contributor hat on: the RepositoryState enum name is not self explanatory, so I wouldn't be broken hearted if it were deprecated and replaced with something more specific.

any proposal for a better name ? This class is used a lot in EGit.

 

That doesn't technically affect this since RepositoryState and RepoState are different identifiers, but it might be nice since then RepoState and RepositoryState would clash less in people's heads too.

Thanks,

Jonathan

--

[Jonathan Nieder]

+jgi...@eclipse.org, repo-discuss -> bcc 

Matthias Sohn wrote[1]:

Jonathan Nieder wrote:

Patrick Hiesel wrote:

 

I have never used JGit's RepositoryState but wanted to bring up potential name clashes by calling out an example.

 

By the way, with my jgit contributor hat on: the RepositoryState enum name is not self explanatory, so I wouldn't be broken hearted if it were deprecated and replaced with something more specific.

any proposal for a better name ? This class is used a lot in EGit.

Good question. I don't have a good idea off the top of my head, which is why I didn't send a change for review on https://git.eclipse.org/r/ making this more concrete.

Git's codebase has a similar concept wt_status_state, but instead of an enum, it is a collection of multiple independent fields (e.g. a cherry-pick and a rebase can be in progress at the same time). One thing I like about that name is that it at least makes it clear that it is about the state of the worktree.

On the other hand, I could imagine "git bisect" working even in a bare repo. So maybe it's about multi-step operations, instead of about the worktree.

The goal of git's "sequencer" subsystem is to control these kinds of multi-step operations (like bisect, merge + resolution + merge --continue, rebase, am, cherry-pick foo..bar, etc). I still haven't come up with a good concise name for MultiCommandOperationState. :/

Thanks,

Jonathan

[1] https://groups.google.com/forum/#!topic/repo-discuss/_BXh5RIkuuM

[Alice Kober-Sotzek]

Dave wrote:

Martin wrote:

Dave wrote:
> Patrick wrote:

> I'm not sure I understand your objection. Are you saying
> that a new developer who sees the term "repo" in
> code/docs/whatever will not understand that "repo" is
> short for "repository"? If so, sorry, I don't buy it,
> that just doesn't seem realistic.

Perhaps not, however "repo" does have the downside of
clashing with the infamous "repo" tool which many Gerrit
devs do have to live with, and likely will for another
decade,

Sure, and for that reason I think the Gerrit documentation should stick with "repository", but within the Gerrit source code I don't see the problem with "repo".

I clearly see the benefits of using "Repo" for class names referring to Gerrit repositories in our source code.

However, I also see some downsides:

* Confusion with the "repo" tool (as already mentioned). For instance, we do have a RepoCommand in the "download-commands" plugin which definitely refers to the "repo" tool. We would need Javadoc descriptions on such classes, clearly stating that those classes refer to the "repo" tool and not to a Gerrit repository.

* Confusion with other Git repository related classes. In our Gerrit code, we have quite some classes which provide additional functionality for Git repositories and which contain the abbreviation "Repo" in their name. I'm thinking of classes like RepoSequence and OpenRepo. To be consistent and avoid confusion, we would need to rename all of those classes to the long form "Repository".

* Deviating from generally accepted naming conventions. According to "Effective Java" #68 (3rd) #56 (2nd), abbreviations should be avoided for class names except for acronyms and certain common abbreviations like min/max. In my opinion, "repo" isn't such a common abbreviation. It might be in the domain of Git and VCS but certainly not globally (and that's what I understand as "common"). For instance, a quick search on the Internet told me that "repo" stands for "repurchase agreement" ;-).

* Onboarding of new contributors is difficult. There are a lot of abbreviations throughout our code base and libraries like JGit. In addition to learning the domain specific language with terms like "revision", "change", "patch set", "tree of a commit", new developers have to learn our internal "abbreviation language" as well. I still can't say that I've internalized JGit's "abbreviation language". I've always accepted that classes like RevWalk and RevCommit are prefixed with "Rev" but I never made the connection to "revision" until recently.

* Finding all classes relating to a Gerrit repository is difficult. When looking for classes named "*Repo*", a bunch of classes show up. There's no way to restrict the classes to only those dealing with Gerrit repositories. In addition, new developers might look for "*Repos*" or "*Reposi*" when trying to locate classes relating to Gerrit repositories and hence wouldn't find the "Repo" classes. For instance, I would have used "*Revi*" as search term to locate revision related classes in JGit and would have totally missed the "Rev..." classes.

* No meaningful distinctions between the terms ("Clean Code" chapter 2). After the renaming, we will have very similarly named classes. For instance, we will have RepoConfig and RepositoryConfig. How should developers know what the difference is?

* Spreading disinformation ("Clean Code" chapter 2). I guess we will use "repo" as variable name for Git repositories as well as for Gerrit repositories. How are we going to avoid confusion in classes which touch both aspects? In addition, how are we avoiding misinterpretation? For instance, "repo.getMaxObjectSizeLimit()" would return a specific setting (which is meanless on its own) of a Gerrit repository (and not the current configuration of the Git repository which I would have guessed just from that line).

All in all, I'm not saying that we shouldn't use "Repo". I just wanted to show that "Repo" is far from being the perfect term. It might still be a good compromise, though.

[Alice Kober-Sotzek]

Edwin wrote:

Martin wrote:

Dave wrote:

> Thanks for the suggestions, Martin.
>
> Martin wrote:
> > In the code, I would be more
> > worried about the conflict with both Jgit and Gerrit's
> > Repository (if we rename the Project object to
> > Repository), but I don't know how much Project is used
> > in the current code base.  The Project object was
> > removed a long time ago from the DB, does it serve much
> > of a purposed any more?
> Good point. ISTM all the fields could be moved to either
> ProjectConfig or ProjectState (using current names, of
> course). Edwin is also thinking of something similar for
> Account/AccountGroup.

Sounds good

As a first step I was only thinking about making Account immutable.

Merging Account into AccountState would be nice, but in the short term it's unlikely that I have time to look into this.

When groups are completely in NoteDb and we have removed the old ReviewDb code, the class AccountGroup is more or less dead anyway. We will only keep using AccountGroup.UUID and AccountGroup.NameKey but all other parts of AccountGroup will simply have been deleted.

[Martin Fick]

On Friday, January 26, 2018 02:46:40 PM Alice Kober-Sotzek
wrote:

> Dave wrote:
> > Martin wrote:
> >> Dave wrote:
> >> > Patrick wrote:
> >> > I'm not sure I understand your objection. Are you
> >> > saying
> >> > that a new developer who sees the term "repo" in
> >> > code/docs/whatever will not understand that "repo" is
> >> > short for "repository"? If so, sorry, I don't buy it,
> >> > that just doesn't seem realistic.
> >>
> >> Perhaps not, however "repo" does have the downside of
> >> clashing with the infamous "repo" tool which many
> >> Gerrit
> >> devs do have to live with, and likely will for another
> >> decade,
> >
> > Sure, and for that reason I think the Gerrit
> > documentation should stick with "repository", but
> > within the Gerrit source code I don't see the problem
> > with "repo".
>
> I clearly see the benefits of using "Repo" for class names
> referring to Gerrit repositories in our source code.
>

> * Confusion with other Git repository related classes. In
> our Gerrit code, we have quite some classes which provide
> additional functionality for Git repositories and which
> contain the abbreviation "Repo" in their name. I'm
> thinking of classes like RepoSequence and OpenRepo. To be
> consistent and avoid confusion, we would need to rename
> all of those classes to the long form "Repository".

I'm not sure there really would be any confusion since they
effectively represent the same thing. If i were to open a
Gerrit Project today, what would I expect to get? Likely a
jgit Repository I think?

> * Deviating from generally accepted naming conventions.
> According to "Effective Java" #68 (3rd) #56 (2nd),
> abbreviations should be avoided for class names except
> for acronyms and certain common abbreviations like
> min/max. In my opinion, "repo" isn't such a common
> abbreviation. It might be in the domain of Git and VCS
> but certainly not globally (and that's what I understand
> as "common"). For instance, a quick search on the
> Internet told me that "repo" stands for "repurchase
> agreement" ;-). * Onboarding of new contributors is
> difficult. There are a lot of abbreviations throughout
> our code base and libraries like JGit. In addition to
> learning the domain specific language with terms like
> "revision", "change", "patch set", "tree of a commit",
> new developers have to learn our internal "abbreviation
> language" as well.

I don't think Repo is particularly hard to understand, and I
would prefer slightly confusing names for new comers that
favor experienced users over
LongJavaNamesBecauseThatIsWhatJavaProgramersOftenLike

> I still can't say that I've
> internalized JGit's "abbreviation language". I've always
> accepted that classes like RevWalk and RevCommit are
> prefixed with "Rev" but I never made the connection to
> "revision" until recently.

Well it doesn't help that many of them are used for things
that one would not associate with revisions. Personally, I
think these would be confusing names, even if they were
RevisionWalk and RevisionCommit.

> * Finding all classes relating to a Gerrit repository is
> difficult. When looking for classes named "*Repo*", a
> bunch of classes show up. There's no way to restrict the
> classes to only those dealing with Gerrit repositories.
> In addition, new developers might look for "*Repos*" or
> "*Reposi*" when trying to locate classes relating to
> Gerrit repositories and hence wouldn't find the "Repo"
> classes. For instance, I would have used "*Revi*" as
> search term to locate revision related classes in JGit
> and would have totally missed the "Rev..." classes.
> * No meaningful distinctions between the terms ("Clean
> Code" chapter 2). After the renaming, we will have very
> similarly named classes. For instance, we will have
> RepoConfig and RepositoryConfig. How should developers
> know what the difference is?

This is a valid concern. It is even more of a concern with
the long form no? Which likely hints that in this classes
case, we might need the something extra like RepoMetaConfig.

> * Spreading disinformation ("Clean Code" chapter 2). I
> guess we will use "repo" as variable name for Git
> repositories as well as for Gerrit repositories. How are
> we going to avoid confusion in classes which touch both
> aspects?

Maybe the Gerrit one really is a conceptual super class of
the jGit one? Should we just make it a super class somehow?

> In addition, how are we avoiding
> misinterpretation? For instance,
> "repo.getMaxObjectSizeLimit()" would return a specific
> setting (which is meanless on its own) of a Gerrit
> repository (and not the current configuration of the Git
> repository which I would have guessed just from that
> line).

But it is more of a Git thing, isn't it. Isn't it a git
thing that Gerrit is happening to enforce?

[Patrick Hiesel]

Thanks for all the discussions so far.

For code, the best suggestion we have so far seems to be Project* => Repo*. As outlined, it is not optimal, but so far there weren't any other suggestions that we deemed as better. Alice suggested to use some additional JavaDoc where needed to clarify between Gerrit/JGit objects.

I'd therefore say we go with it.

For the API/docs I think the consensus was to stick with the long form as it makes things easier to understand for the user and also the reasons we have in code for going with Repo (e.g. clash with JGit) doesn't apply there.

I'd probably start working on this next week, so feel free to object (now) if you don't like the proposed path :)

If you have spare cycles to work on this, then that'd be great, too!

Thanks!

[Patrick Hiesel]

Since nobody shouted at me and there have been no vetos I started with the implementation today.

I have a specific question about the level of compatibility that is required.

For the REST API, we will basically provide compatibility for the old identifier ("project") pretty much indefinitely with the option to turn off compatibility using a gerrit.config option.

The plan is to write a "project" key-value pair whenever a "repository" key-value pair is written and replace "project" keys with "repository" keys for request that Gerrit receives. A proof-of-concept for this can be found here. 

The question is now centered around the Java extension API. We will definately remove the term "project" from code at some point but we could offer a version of Gerrit that works with both "project" and "repository" so that plugin authors can migrate their plugins.

In terms of code, this compatibility layer comes with a lot of technical dept for core Gerrit since we use "project" in package names, attribute names etc. So we would basically have to duplicate certain classes to keep them available on the old package name.

Could plugin authors live without the aforementioned compatibility release?

Thanks!

[David Ostrovsky]

Am Mittwoch, 24. Januar 2018 11:24:23 UTC+1 schrieb Patrick Hiesel:

Hi,

we discussed on a recent hackathon, that we want to rename "project" to "repository" in Gerrit and from what I recall there was consensus about that.

Sorry, I wasn't able to attend the hackathon and participate in this discussion.
 

We looked into this a bit more and wanted to discuss a proposal before heading into the implementation.

Motivation

Users know Git. In Git you have repositories. Gerrit calls these projects and it is not immediately clear that repo == project. Renaming will lower the entry barrier to Gerrit.

I'm late to the party but I would like to keep the current name project in Gerrit.

I have never heard any complaints that this name is confusing. I'm working with Gerrit for 5 years now.
Can you point me to any discussions on the mailing list or any high ranked issues in the issue tracker?

I think that project is the right name, for number of reasons:

* Project in Gerrit conceptually is much more then just Git repository. Permisions are fundamental Gerrit feature
and the Gerrit poject is where the persmissions are configured, by defining the project ACLs with project inheritance scheme.
That way, the project in Gerrit is Git repository + meta data. We should do a better job in gerrit documentation and explain
to the users, what the project is and why it is not just called repository: it's more than that.

* Consistency with abstract terms in Gerrit: Why you havn't suggested to rename the term "change" to "commit"? With the
same argumentation here: Users know Git, change is commit in Git, let us just rename change to commit in Gerrit. Similar
reason to project: while it's technically correct, change in Gerrit is much more then just Git commit: it is commit + meta data
(votes, human comments, bot comments, verification logs, etc).

* Open Gerrit Code Review for other (D)VCS backends. Today gerrit only supports Git, but
conceptually, Gerrit can be opened for other backend systems in the future. What if the name for other backends is different
as it's in Git? Would we rename to more abstract name Project back again?

* Existing tools/integrations/libraries: In the last 10 years many tools, intergrations, libraries
UI extensions were written (open and closed source). They would need to be adjusted to reflect
this change in gerrit core. That would require a *lot* of efforts.

* Gerrit way/thinking/legacy: it should stay the way gerrit users used to. Why should we replace
the major Gerrit term, just because it is called differently in the tools foo/bar?

* Wrong time frame/Migration of ReviewDB->NoteDb/PG -> GWT UI is underway:

That why I would like to keep the current name. Moreover, I would *really* like to avoid changing it now:
2.15 wasn't released, stable-2.16/stable-3.0 wasn't cut of, ReviewDb wasn't removed yet and GWT UI
is still there. Those migrations, replacements of backend and the UI, tool chain adaptations from
SQL scripts to NoteDb programms, plugins transitions to new backend and new UI, all this is a huge
change for Gerrit users and administrators.

Should we really throw on them yet another substantial migration pain at *the same* time:

* Change the PG-UI
* Change (to be removed) GWT-UI?
* Change URL scheme (again)
* Change all refs/meta/config files from project.config to repository.config for core and plugins
* Change plugin API (with requirements to adapt all plugins, that need to be adapted to PG UI first)
* Rename All-Projects to All-Repositories,
* Rename plugins from delete-projects to delete-repository
* Rename project secondary index to repository secondary index
...

If you still want to change that, can't we wait until NoteDb and PG transition is completed,
ReviewDb and GWT-UI are removed and stable-3.1 was cut of?

[Luca Milanesio]

> On 15 Feb 2018, at 14:19, David Ostrovsky <david.o...@gmail.com> wrote:
>
>
> Am Mittwoch, 24. Januar 2018 11:24:23 UTC+1 schrieb Patrick Hiesel:
> Hi,
>
> we discussed on a recent hackathon, that we want to rename "project" to "repository" in Gerrit and from what I recall there was consensus about that.
>
>
> Sorry, I wasn't able to attend the hackathon and participate in this discussion.

I believe that the feedback was: "why did we even called it project the first time? repository seems a more logical name"

>
> We looked into this a bit more and wanted to discuss a proposal before heading into the implementation.
>
> Motivation
> Users know Git. In Git you have repositories. Gerrit calls these projects and it is not immediately clear that repo == project. Renaming will lower the entry barrier to Gerrit.

Yes, that is the first feedback I get from people that start using Gerrit for the first time.

The second problem they have is to understand what is a "Change" and a "Patch-Set". They typically want to talk about pull-request.

>
>
> I'm late to the party but I would like to keep the current name project in Gerrit.
>
> I have never heard any complaints that this name is confusing. I'm working with Gerrit for 5 years now.
> Can you point me to any discussions on the mailing list or any high ranked issues in the issue tracker?

The point is: once you start using Gerrit for at least 1-2 days, you don't have the confusion anymore. That is why it is so difficult to find the evidence you are talking about.

>
> I think that project is the right name, for number of reasons:
>
> * Project in Gerrit conceptually is much more then just Git repository. Permisions are fundamental Gerrit feature
> and the Gerrit poject is where the persmissions are configured, by defining the project ACLs with project inheritance scheme.
> That way, the project in Gerrit is Git repository + meta data. We should do a better job in gerrit documentation and explain
> to the users, what the project is and why it is not just called repository: it's more than that.

Agreed.

>
> * Consistency with abstract terms in Gerrit: Why you havn't suggested to rename the term "change" to "commit"? With the
> same argumentation here: Users know Git, change is commit in Git, let us just rename change to commit in Gerrit. Similar
> reason to project: while it's technically correct, change in Gerrit is much more then just Git commit: it is commit + meta data
> (votes, human comments, bot comments, verification logs, etc).

That was exactly the point I've mentioned before: change and patch-sets are as well "unknown terms" for the Gerrit novice user.

>
> * Open Gerrit Code Review for other (D)VCS backends. Today gerrit only supports Git, but
> conceptually, Gerrit can be opened for other backend systems in the future. What if the name for other backends is different
> as it's in Git? Would we rename to more abstract name Project back again?

Wow, yes, but we are miles away from it, correct?
With NoteDb, I struggle to see Gerrit being able to store its data into a Subversion-based NoteDb :-D

>
> * Existing tools/integrations/libraries: In the last 10 years many tools, intergrations, libraries
> UI extensions were written (open and closed source). They would need to be adjusted to reflect
> this change in gerrit core. That would require a *lot* of efforts.

And documentation, blog posts, videos, papers, books (including mine), etc ...

>
> * Gerrit way/thinking/legacy: it should stay the way gerrit users used to. Why should we replace
> the major Gerrit term, just because it is called differently in the tools foo/bar?
>
> * Wrong time frame/Migration of ReviewDB->NoteDb/PG -> GWT UI is underway:

Is there a "good time" at all? Such a major name change has never a "right time" :-)

>
> That why I would like to keep the current name. Moreover, I would *really* like to avoid changing it now:
> 2.15 wasn't released, stable-2.16/stable-3.0 wasn't cut of, ReviewDb wasn't removed yet and GWT UI
> is still there. Those migrations, replacements of backend and the UI, tool chain adaptations from
> SQL scripts to NoteDb programms, plugins transitions to new backend and new UI, all this is a huge
> change for Gerrit users and administrators.

This is very true: can we just wait to start stabilizing 3.0?

>
> Should we really throw on them yet another substantial migration pain at *the same* time:
>
> * Change the PG-UI
> * Change (to be removed) GWT-UI?
> * Change URL scheme (again)
> * Change all refs/meta/config files from project.config to repository.config for core and plugins
> * Change plugin API (with requirements to adapt all plugins, that need to be adapted to PG UI first)
> * Rename All-Projects to All-Repositories,
> * Rename plugins from delete-projects to delete-repository
> * Rename project secondary index to repository secondary index
> ...
>
> If you still want to change that, can't we wait until NoteDb and PG transition is completed,
> ReviewDb and GWT-UI are removed and stable-3.1 was cut of?

That's a good point, +1 to it.

Overall I like change, especially if it is driven in extending the audience and the community around Gerrit. However, one thing at a time :-)

Luca.

>
>
> --
> --
> To unsubscribe, email repo-discuss...@googlegroups.com

> More info at http://groups.google.com/group/repo-discuss?hl=en
>
> ---
> You received this message because you are subscribed to the Google Groups "Repo and Gerrit Discussion" group.

> To unsubscribe from this group and stop receiving emails from it, send an email to repo-discuss...@googlegroups.com.

[Patrick Hiesel]

On Thu, Feb 15, 2018 at 3:36 PM Luca Milanesio <luca.mi...@gmail.com> wrote:

> On 15 Feb 2018, at 14:19, David Ostrovsky <david.o...@gmail.com> wrote:
>
>
> Am Mittwoch, 24. Januar 2018 11:24:23 UTC+1 schrieb Patrick Hiesel:
> Hi,
>
> we discussed on a recent hackathon, that we want to rename "project" to "repository" in Gerrit and from what I recall there was consensus about that.
>
>
> Sorry, I wasn't able to attend the hackathon and participate in this discussion.

I believe that the feedback was: "why did we even called it project the first time? repository seems a more logical name"

>
> We looked into this a bit more and wanted to discuss a proposal before heading into the implementation.
>
> Motivation
> Users know Git. In Git you have repositories. Gerrit calls these projects and it is not immediately clear that repo == project. Renaming will lower the entry barrier to Gerrit.

Yes, that is the first feedback I get from people that start using Gerrit for the first time.

The second problem they have is to understand what is a "Change" and a "Patch-Set". They typically want to talk about pull-request.

>
>
> I'm late to the party but I would like to keep the current name project in Gerrit.
>
> I have never heard any complaints that this name is confusing. I'm working with Gerrit for 5 years now.
> Can you point me to any discussions on the mailing list or any high ranked issues in the issue tracker?

The point is: once you start using Gerrit for at least 1-2 days, you don't have the confusion anymore. That is why it is so difficult to find the evidence you are talking about.

>
> I think that project is the right name, for number of reasons:
>
> * Project in Gerrit conceptually is much more then just Git repository. Permisions are fundamental Gerrit feature
> and the Gerrit poject is where the persmissions are configured, by defining the project ACLs with project inheritance scheme.
> That way, the project in Gerrit is Git repository + meta data. We should do a better job in gerrit documentation and explain
> to the users, what the project is and why it is not just called repository: it's more than that.

Agreed.

I agree that we should have really good documentation, but users don't like reading docs and one of the problems first-time users have when the come to Gerrit is that they do have to read docs. I think this renaming is one step towards lowering that entry barrier.

 

>
> * Consistency with abstract terms in Gerrit: Why you havn't suggested to rename the term "change" to "commit"? With the
> same argumentation here: Users know Git, change is commit in Git, let us just rename change to commit in Gerrit. Similar
> reason to project: while it's technically correct, change in Gerrit is much more then just Git commit: it is commit + meta data
> (votes, human comments, bot comments, verification logs, etc).

That was exactly the point I've mentioned before: change and patch-sets are as well "unknown terms" for the Gerrit novice user.

>
> * Open Gerrit Code Review for other (D)VCS backends. Today gerrit only supports Git, but
> conceptually, Gerrit can be opened for other backend systems in the future. What if the name for other backends is different
> as it's in Git? Would we rename to more abstract name Project back again?

Wow, yes, but we are miles away from it, correct?
With NoteDb, I struggle to see Gerrit being able to store its data into a Subversion-based NoteDb :-D

:)

 

>
> * Existing tools/integrations/libraries: In the last 10 years many tools, intergrations, libraries
> UI extensions were written (open and closed source). They would need to be adjusted to reflect
> this change in gerrit core. That would require a *lot* of efforts.

And documentation, blog posts, videos, papers, books (including mine), etc ...

They don't have to adapt if they don't want to - at least not in code.

The plan is to keep the compatibility for 'project' in the REST API pretty much forever: https://gerrit-review.googlesource.com/c/gerrit/+/158932

The the only tools that have to adapt right away are the ones who are based on the Java extension API. Markus said earlier on that he doesn't see a large problem in that since it is really just a trivial rename.

 

>
> * Gerrit way/thinking/legacy: it should stay the way gerrit users used to. Why should we replace
> the major Gerrit term, just because it is called differently in the tools foo/bar?
>
> * Wrong time frame/Migration of ReviewDB->NoteDb/PG -> GWT UI is underway:


Is there a "good time" at all? Such a major name change has never a "right time" :-)

Agreed. We thought 3.0 would be a *reasonable* time because a major release number increase hints at more substantial changes. However, I also agree that we are already forcing a lot of changes onto users and administrators.

 

>
> That why I would like to keep the current name. Moreover, I would *really* like to avoid changing it now:
> 2.15 wasn't released, stable-2.16/stable-3.0 wasn't cut of, ReviewDb wasn't removed yet and GWT UI
> is still there. Those migrations, replacements of backend and the UI, tool chain adaptations from
> SQL scripts to NoteDb programms, plugins transitions to new backend and new UI, all this is a huge
> change for Gerrit users and administrators.

This is very true: can we just wait to start stabilizing 3.0?

>
> Should we really throw on them yet another substantial migration pain at *the same* time:
>
> * Change the PG-UI
> * Change (to be removed) GWT-UI?
> * Change URL scheme (again)
> * Change all refs/meta/config files from project.config to repository.config for core and plugins
> * Change plugin API (with requirements to adapt all plugins, that need to be adapted to PG UI first)
> * Rename All-Projects to All-Repositories,
> * Rename plugins from delete-projects to delete-repository
> * Rename project secondary index to repository secondary index
> ...
>
> If you still want to change that, can't we wait until NoteDb and PG transition is completed,
> ReviewDb and GWT-UI are removed and stable-3.1 was cut of?

That's a good point, +1 to it.

Overall I like change, especially if it is driven in extending the audience and the community around Gerrit. However, one thing at a time :-)

Luca.

I see good reasons for this to be either in 3.0 (major release, people expect larger changes) or 3.1 (won't carry so many changes, so this renaming will be easier to digest).

Can we make this dependent on when we cut off 3.0?

[David Ostrovsky]

Am Donnerstag, 15. Februar 2018 15:58:08 UTC+1 schrieb Patrick Hiesel:

On Thu, Feb 15, 2018 at 3:36 PM Luca Milanesio <luca.mi...@gmail.com> wrote:

> On 15 Feb 2018, at 14:19, David Ostrovsky <david.o...@gmail.com> wrote:
>
>
> Am Mittwoch, 24. Januar 2018 11:24:23 UTC+1 schrieb Patrick Hiesel:
> Hi,
>
> we discussed on a recent hackathon, that we want to rename "project" to "repository" in Gerrit and from what I recall there was consensus about that.
>
>
> Sorry, I wasn't able to attend the hackathon and participate in this discussion.

I believe that the feedback was: "why did we even called it project the first time? repository seems a more logical name"

>
> We looked into this a bit more and wanted to discuss a proposal before heading into the implementation.
>
> Motivation
> Users know Git. In Git you have repositories. Gerrit calls these projects and it is not immediately clear that repo == project. Renaming will lower the entry barrier to Gerrit.

Yes, that is the first feedback I get from people that start using Gerrit for the first time.

The second problem they have is to understand what is a "Change" and a "Patch-Set". They typically want to talk about pull-request.

Exactly, thanks for pointing this out. Without redaing the documentation, or asking for explanation,
nobody would understand what Change and Patch Set terms mean. Renaming project to repository
*only* but letting the Change and Patch Set terms "as is" doesn't solve and change anything.

>
>
> I'm late to the party but I would like to keep the current name project in Gerrit.
>
> I have never heard any complaints that this name is confusing. I'm working with Gerrit for 5 years now.
> Can you point me to any discussions on the mailing list or any high ranked issues in the issue tracker?

The point is: once you start using Gerrit for at least 1-2 days, you don't have the confusion anymore. That is why it is so difficult to find the evidence you are talking about.

>
> I think that project is the right name, for number of reasons:
>
> * Project in Gerrit conceptually is much more then just Git repository. Permisions are fundamental Gerrit feature
> and the Gerrit poject is where the persmissions are configured, by defining the project ACLs with project inheritance scheme.
> That way, the project in Gerrit is Git repository + meta data. We should do a better job in gerrit documentation and explain
> to the users, what the project is and why it is not just called repository: it's more than that.

Agreed.

I agree that we should have really good documentation, but users don't like reading docs and one of the problems first-time users have when the come to Gerrit is that they do have to read docs. I think this renaming is one step towards lowering that entry barrier.

Nope. It doesn't bring you any step towards. See Change and Patch Set terms discussion above,
mentioned by Luca.

If you are trying to make Gerrit a GitHub clone, fine, but then, be consistent and propose the complete
gerrit GitHubation renaming procedure:

* Project => Repository
* Change => Pull Request
* Patch Set => Commit

Before you do this, I already say now that I would disagree ;-)

[Patrick Hiesel]

On Thu, Feb 15, 2018 at 4:16 PM David Ostrovsky <david.o...@gmail.com> wrote:

Am Donnerstag, 15. Februar 2018 15:58:08 UTC+1 schrieb Patrick Hiesel:

On Thu, Feb 15, 2018 at 3:36 PM Luca Milanesio <luca.mi...@gmail.com> wrote:

> On 15 Feb 2018, at 14:19, David Ostrovsky <david.o...@gmail.com> wrote:
>
>
> Am Mittwoch, 24. Januar 2018 11:24:23 UTC+1 schrieb Patrick Hiesel:
> Hi,
>
> we discussed on a recent hackathon, that we want to rename "project" to "repository" in Gerrit and from what I recall there was consensus about that.
>
>
> Sorry, I wasn't able to attend the hackathon and participate in this discussion.

I believe that the feedback was: "why did we even called it project the first time? repository seems a more logical name"

>
> We looked into this a bit more and wanted to discuss a proposal before heading into the implementation.
>
> Motivation
> Users know Git. In Git you have repositories. Gerrit calls these projects and it is not immediately clear that repo == project. Renaming will lower the entry barrier to Gerrit.

Yes, that is the first feedback I get from people that start using Gerrit for the first time.

The second problem they have is to understand what is a "Change" and a "Patch-Set". They typically want to talk about pull-request.

Exactly, thanks for pointing this out. Without redaing the documentation, or asking for explanation,
nobody would understand what Change and Patch Set terms mean. Renaming project to repository
*only* but letting the Change and Patch Set terms "as is" doesn't solve and change anything.

I think perfect shouldn't be the enemy of good (no, I am not saying that renaming change to pull request would make Gerrit perfect ;) - but 'complete' following this argument).

 

>
>
> I'm late to the party but I would like to keep the current name project in Gerrit.
>
> I have never heard any complaints that this name is confusing. I'm working with Gerrit for 5 years now.
> Can you point me to any discussions on the mailing list or any high ranked issues in the issue tracker?

The point is: once you start using Gerrit for at least 1-2 days, you don't have the confusion anymore. That is why it is so difficult to find the evidence you are talking about.

>
> I think that project is the right name, for number of reasons:
>
> * Project in Gerrit conceptually is much more then just Git repository. Permisions are fundamental Gerrit feature
> and the Gerrit poject is where the persmissions are configured, by defining the project ACLs with project inheritance scheme.
> That way, the project in Gerrit is Git repository + meta data. We should do a better job in gerrit documentation and explain
> to the users, what the project is and why it is not just called repository: it's more than that.

Agreed.

I agree that we should have really good documentation, but users don't like reading docs and one of the problems first-time users have when the come to Gerrit is that they do have to read docs. I think this renaming is one step towards lowering that entry barrier.

Nope. It doesn't bring you any step towards. See Change and Patch Set terms discussion above,
mentioned by Luca.

If you are trying to make Gerrit a GitHub clone, fine, but then, be consistent and propose the complete
gerrit GitHubation renaming procedure:

* Project => Repository
* Change => Pull Request
* Patch Set => Commit

Before you do this, I already say now that I would disagree ;-)

I also disagree :)

[Logan Hanks]

On Thu, Feb 15, 2018 at 7:16 AM David Ostrovsky <david.o...@gmail.com> wrote:

Am Donnerstag, 15. Februar 2018 15:58:08 UTC+1 schrieb Patrick Hiesel:

On Thu, Feb 15, 2018 at 3:36 PM Luca Milanesio <luca.mi...@gmail.com> wrote:

> On 15 Feb 2018, at 14:19, David Ostrovsky <david.o...@gmail.com> wrote:
>
>
> Am Mittwoch, 24. Januar 2018 11:24:23 UTC+1 schrieb Patrick Hiesel:
> Hi,
>
> we discussed on a recent hackathon, that we want to rename "project" to "repository" in Gerrit and from what I recall there was consensus about that.
>
>
> Sorry, I wasn't able to attend the hackathon and participate in this discussion.

I believe that the feedback was: "why did we even called it project the first time? repository seems a more logical name"

>
> We looked into this a bit more and wanted to discuss a proposal before heading into the implementation.
>
> Motivation
> Users know Git. In Git you have repositories. Gerrit calls these projects and it is not immediately clear that repo == project. Renaming will lower the entry barrier to Gerrit.

Yes, that is the first feedback I get from people that start using Gerrit for the first time.

The second problem they have is to understand what is a "Change" and a "Patch-Set". They typically want to talk about pull-request.

Exactly, thanks for pointing this out. Without redaing the documentation, or asking for explanation,
nobody would understand what Change and Patch Set terms mean. Renaming project to repository
*only* but letting the Change and Patch Set terms "as is" doesn't solve and change anything.

I agree that this is an incomplete change if we don't address all the other confusing concepts for new Gerrit users, but that's the nature of developing software. Saying that a partial solution doesn't solve anything is an exaggeration and sets an impossible bar to meet. Unless we were to come up with a plan to change every concept in Gerrit simultaneously with a once-in-a-decade significant release, we would be stuck with the status quo perpetually. I don't think any of us considers Gerrit to be a "finished" project.

David, does it change how you feel if you divide your concerns into two independent parts? One is "in an ideal world, what would we call projects?" The other is, "given an ideal name for projects, when would we make the transition?" The term "repository" seems like a strong candidate for the first concern. I know you favor "project", but if you divorce that concern from the timing concern, do you still favor the name as much? You still have the option of favoring the timing of "3.0" or "never" or whatever you prefer for the second concern, but it would be a significant step forward if we can agree on a name.

[Oswald Buddenhagen]

On Thu, Feb 15, 2018 at 04:58:06PM +0000, 'Logan Hanks' via Repo and Gerrit Discussion wrote:
> David, does it change how you feel if you divide your concerns into two
> independent parts? One is "in an ideal world, what would we call
> projects?" The other is, "given an ideal name for projects, when would we
> make the transition?" The term "repository" seems like a strong candidate
> for the first concern. I know you favor "project", but if you divorce that
> concern from the timing concern, do you still favor the name as much? You
> still have the option of favoring the timing of "3.0" or "never" or
> whatever you prefer for the second concern, but it would be a significant
> step forward if we can agree on a name.

may i suggest that all the time already spent on deliberating the
rename, let alone later implementing it and dealing with the fallout
"downstream", exceeds the *cumulative* time saved on future users' side?

seriously, among all the other things one has to learn to start using
gerrit, the mild misnomer "project" is really a rather irrelevant
concern.
i suppose it might be different if
https://bugs.chromium.org/p/gerrit/issues/detail?id=1008 was
implemented, but even then it can be worked around by calling the bigger
scope "organization" or something like that.

regarding "change" vs. "pull request" ... the latter is a plain misnomer
(did you ever think about what this term actually means and where it
comes from?). gitorous used "merge request" which is somewhat more
applicable (hey, shouldn't that be "submission request" then? or
"integration request"? shall the concept's name be configurable? :D).
renaming "change" would also imply renaming the Change-Id footer, which
leaves a visible mess in a project's (err, repo's) git history.

renaming "patch set" to "revision" would seem to be the least disruptive
and actually most helpful in my estimation. don't call it "commit", as
that would *increase* the confusion potential with what "change"
currently means (though technically, commit and revision are the same
thing in git, so this is actually a rather weak distinction).

in the end, i'd say that all that renaming is a profoundly misguided
idea - the gain is minimal (even if the current names are suboptimal,
you can't map the concepts directly to git or github, so new users will
face some unfamiliar terms anyway), and causes significant migration
pain at all levels.

[Patrick Hiesel]

On Mon, Feb 19, 2018 at 5:43 PM Oswald Buddenhagen <oswald.bu...@gmx.de> wrote:

On Thu, Feb 15, 2018 at 04:58:06PM +0000, 'Logan Hanks' via Repo and Gerrit Discussion wrote:
>    David, does it change how you feel if you divide your concerns into two
>    independent parts? One is "in an ideal world, what would we call
>    projects?" The other is, "given an ideal name for projects, when would we
>    make the transition?" The term "repository" seems like a strong candidate
>    for the first concern. I know you favor "project", but if you divorce that
>    concern from the timing concern, do you still favor the name as much? You
>    still have the option of favoring the timing of "3.0" or "never" or
>    whatever you prefer for the second concern, but it would be a significant
>    step forward if we can agree on a name.

may i suggest that all the time already spent on deliberating the
rename, let alone later implementing it and dealing with the fallout
"downstream", exceeds the *cumulative* time saved on future users' side?

We are willing to make all the investment required to get this done in Gerrit core, as well as all core plugins + some additional ones where we know that they are frequently used ourselves.

The REST API will remain 100% compatible, so this should also not be a concern.

One concern I share is that plugins that we don't host on gerrit.googlesource.com will have to migrate. To be honest there are always quite a number of things changing because the Gerrit project has to evolve (new UI, PermissionBackend, refactorings etc.).

Compared to those changes, a simple compiler-assisted rename seems relatively cheap to me.

 

seriously, among all the other things one has to learn to start using
gerrit, the mild misnomer "project" is really a rather irrelevant
concern.
i suppose it might be different if
https://bugs.chromium.org/p/gerrit/issues/detail?id=1008 was
implemented, but even then it can be worked around by calling the bigger
scope "organization" or something like that.

regarding "change" vs. "pull request" ... the latter is a plain misnomer
(did you ever think about what this term actually means and where it
comes from?). gitorous used "merge request" which is somewhat more
applicable (hey, shouldn't that be "submission request" then? or
"integration request"? shall the concept's name be configurable? :D).
renaming "change" would also imply renaming the Change-Id footer, which
leaves a visible mess in a project's (err, repo's) git history.

Wait, nobody seriously suggested renaming change to pull-request at this point. It was mentioned in a discussion about if we should consider fixing all the names we currently see as hard to understand.

I absolutely share your opinion that pull request does not accurately represent what a change is in Gerrit. IMHO this concern does not apply to the project to repository renaming.

 

renaming "patch set" to "revision" would seem to be the least disruptive
and actually most helpful in my estimation. don't call it "commit", as
that would *increase* the confusion potential with what "change"
currently means (though technically, commit and revision are the same
thing in git, so this is actually a rather weak distinction).

Personally, I do think that this could be a sensible rename. But as Logan previously said, it would be nice to do one thing at a time :)

 

in the end, i'd say that all that renaming is a profoundly misguided
idea - the gain is minimal (even if the current names are suboptimal,
you can't map the concepts directly to git or github, so new users will
face some unfamiliar terms anyway), and causes significant migration
pain at all levels.

[Martin Fick]

On Thursday, February 15, 2018 06:19:13 AM David Ostrovsky
wrote:

> Am Mittwoch, 24. Januar 2018 11:24:23 UTC+1 schrieb
Patrick Hiesel:
> > Hi,
> >
> > we discussed on a recent hackathon, that we want to
> > rename "project" to "repository" in Gerrit and from
> > what I recall there was consensus about that.
>
> Sorry, I wasn't able to attend the hackathon and
> participate in this discussion.

I may have been the one to come up with the proposal. I
suggested the shift when I realized that the term "Project"
was so generic that in our conversations we had to say
"Project, i.e. the git repository" to distinguish it from
other high level project concepts such as Android, Chrome...
When I realized that I had to specify what type of project I
meant, that perhaps the term was too vague, and that perhaps
little would be lost if we just used the term repository
instead. I then also realized it likely would be easier for
new comers.

> I have never heard any complaints that this name is
> confusing. I'm working with Gerrit for 5 years now.

Sorry, consider my complaint registered above.

> I think that project is the right name, for number of
> reasons:
>
> * Project in Gerrit conceptually is much more then just
> Git repository. Permisions are fundamental Gerrit feature
> and the Gerrit poject is where the persmissions are
> configured, by defining the project ACLs with project
> inheritance scheme. That way, the project in Gerrit is
> Git repository + meta data. We should do a better job in
> gerrit documentation and explain to the users, what the
> project is and why it is not just called repository: it's
> more than that.

While these are all true statements, I feel that nothing is
fundamentally lost by using the term Repository. People
think of a project as the git information and could care
less that the repository happens to also store additional
Gerrit info in it. When I clone --mirror a gerrit project
to my local disk, do I end up with a project or a
repository?

> * Consistency with abstract terms in Gerrit: Why you
> havn't suggested to rename the term "change" to "commit"?

A change does not equate to a commit, a commit equates to a
change patchset. That being said, a better term for change
should be considered if there is one. But a change does do
a pretty good job explaining what it is. Is there a better
git term?

> * Open Gerrit Code Review for other (D)VCS backends. Today
> gerrit only supports Git, but
> conceptually, Gerrit can be opened for other backend
> systems in the future. What if the name for other
> backends is different as it's in Git? Would we rename to
> more abstract name Project back again?

Imagine that we started out with the term repository and
then we added a DVCS with some other term for its
repository. At that point we might look for another term
like "Project", but along the way I think we would all
think, "ugh this sucks having to come up with a term that
isn't as obvious and clear to new users as what the DVCSes
use"? Maybe we would just stick with the specific terms
for each DVCS to make it clear?

> * Wrong time frame/Migration of ReviewDB->NoteDb/PG -> GWT
> UI is underway:

I am not involved enough upstream to be able to comment on
this, and I respect your points about it possibly not being
a good time,

[Oswald Buddenhagen]

On Tue, Feb 20, 2018 at 09:15:53AM +0000, 'Patrick Hiesel' via Repo and Gerrit Discussion wrote:
> On Mon, Feb 19, 2018 at 5:43 PM Oswald Buddenhagen <oswald.bu...@gmx.de> wrote:
> > may i suggest that all the time already spent on deliberating the
> > rename, let alone later implementing it and dealing with the fallout
> > "downstream", exceeds the *cumulative* time saved on future users' side?
>
> We are willing to make all the investment required to get this done in
> Gerrit core, as well as all core plugins + some additional ones where we
> know that they are frequently used ourselves.
> The REST API will remain 100% compatible, so this should also not be a
> concern.
>

that means that you'll need to duplicate the field when you return data.
that's wasteful, ugly, and confusing.

> One concern I share is that plugins that we don't host on
> gerrit.googlesource.com will have to migrate. To be honest there are
> always quite a number of things changing because the Gerrit project has to
> evolve (new UI, PermissionBackend, refactorings etc.).
> Compared to those changes, a simple compiler-assisted rename seems
> relatively cheap to me.
>

the change is small, but still requires adjustments in 3rd party code
(you are not going to keep backwards compat indefinitely, even if you
manage to be 100% compatible initially).

given that the real-world benefit of the change is negligible, the
acceptable price is accordingly small.

if you *really really* want that, change what the frontend shows and
adjust the docu, and accept "repo" and "repository" as aliases for
"project" in search queries (and maybe other places where end-users
would enter it manually). but don't change APIs and class names. the
discrepancy is easily explained and without practical impact (the two
terms are virtually synonymous for anyone who worked with gerrit for
more than a few hours anyway).

[David Ostrovsky]

On Tuesday, February 20, 2018 at 7:39:00 PM UTC+1, MartinFick wrote:

On Thursday, February 15, 2018 06:19:13 AM David Ostrovsky
wrote:
> Am Mittwoch, 24. Januar 2018 11:24:23 UTC+1 schrieb
Patrick Hiesel:
> > Hi,
> >
> > we discussed on a recent hackathon, that we want to
> > rename "project" to "repository" in Gerrit and from
> > what I recall there was consensus about that.
>
> Sorry, I wasn't able to attend the hackathon and
> participate in this discussion.

I may have been the one to come up with the proposal.  I
suggested the shift when I realized that the term "Project"
was so generic that in our conversations we had to say
"Project, i.e. the git repository" to distinguish it from
other high level project concepts such as Android, Chrome...  
When I realized that I had to specify what type of project I
meant, that perhaps the term was too vague, and that perhaps
little would be lost if we just used the term repository
instead.

Just say Android Organization, Gerrit project and Git repository

and move forward with the life?

I believe that Gerrit founder made very wise and conscious decision and

preferred to separate those two concerns to avoid the ambiguity and collision

between Gerrit project and Git repository. Term Repository is very much

overloaded in DVCS domain in general and in Git in particular. Keeping

a different name clearly reduces the scope in discussion and avoids confusion.

Today if I say All-Projects it is clear what I mean. When I say all repositories,

what is that? Today if I say: project config. It's clear that I mean gerrit project

configuration file on refs/meta/config branch. If I say repository config what do

I mean? Gerrit repository config file on refs/meta/config branch or Git's own

repository config file? And so on. Just check the developers discussion on this

thread about concept collision between Gerrit projects renamed to repository

and JGit repository. The collision problem is of course not just the problem of

gerrit code base, but the whole DVCS domain, and all gerrit extensions, plugins

and libraries would suffer from that collision and ambiguity.

I disagree with your problem statement to start with. You already did a wrong

assessment and voted -2 on Dave's proposal to discontinue vote squashing

machinery during change reindex operation in another dicsussion thread.

Yesterday as I cherry-picked that series to stable-2.15 not only it fixed intermittent

secondary index corruption problem but it also significantly reduced reindexing

time on my test site. This was an innocent mistake with no consequences at all.

Your current proposal, to unconditionally rename major gerrit term with suggested

scope would cause incredible mess and migration pain for thousands of gerrit

installation on all levels:

* Change the PG-UI
* Change (to be removed) GWT-UI?
* Change URL scheme (again)
* Change all refs/meta/config files from project.config to repository.config for core and plugins
* Change plugin API (with requirements to adapt all plugins, that need to be adapted to PG UI first)
* Rename All-Projects to All-Repositories,
* Rename plugins from delete-projects to delete-repository

* Rename project predicate to repository predicate in changes secondary index

* Rename project secondary index to repository secondary index

* Rename project parameter in all SSH commands

...

All that without any benefits and advantages for this project. (If this move would

provide us open source multi-master solution I would think twice, but...).

Bottom line: while this rename may solve some problem, it would introduce new, 

much severe ambiguity and collision problems in Gerit and Git domain.

 I then also realized it likely would be easier for
new comers.

I agree with problem statement: Make gerrit more accessible and lower

the enter barrier for new gerrit users. I disagree with your conclusion.

First of all, let me say that: I don't know what gerrit users you have in mind,

when you say that they have problem to grasp that one abstraction level after

reading 60 seconds gerrit tutorial that should carefully explain major gerrit

concepts and say about the Gerrit Project something like:

Gerrit project is ACL, project inheritance, Submit type strategy, plus other project

properties, like should change-Id footer be mandatory or optional, etc and of

course primary Git repository. Moreover, In Gerrit Projects other git repositories can be

specified: mirror_1, ..., mirror_n, that are saved in replication configuration file, but

but the gerrit users don't care where the stuff is saved.

Every undergraduate student understands that statement. If they don't they should

stop here and change the job.

The gerrit users that I'm talking about and instructed to use gerrit in last

5 years, in both open source and enterprise contexts, are highly qualified

software engineers. It's also clear why: Gerrit is Pre-Submit code review tool

even though we opened it recently for post merge review workflow. Such tool

is mostly used in agile environment, with Scrum, Kanban and other agile workflow.

Mostly other agile tools, Continuous Integration, Continuous Delivery processes

are used. In short, Gerrit users are Scrum master, Product owners, or devops.

You are trying to solve a problem that doesn't exist. Gerrit users don't have a problem

of understanding of Gerrit Project/Git Repository terms.

I do agree that new gerrit users (that using gerrit < 2 days) do have an issues to

understand major gerrit workflows. We have too many workflows, some of them are

obscure and we should try hard to improve that (in fact, I removed insane draft change

and draft patch set workflow and replaced with with sane Work-In-Progress workflow).

This problem is not unique to gerrit code review, though. Other (git based) collaboration

tools have the same complex-workflow-problem, e.g.: Sync GitHub fork. It is not that

obvious. But then you find this step-by-step tutorial, with only 5 steps:

https://help.github.com/articles/syncing-a-fork/

screenshots, clear pre-requisites statement and references to another step-by-step:

tutorial "configure a remote that points to the upstream repository init"

I believe that providing such step-by-step tutorials for different gerrit workflows would

be a major step in the right direction.

* setup authentication

* push change for review

* address comments

* rebase your change from UI and command line

* Amend change locally, download, amend, push

* Work-In-Progress workflow

* Inline Edit Workflow

* Cherry-pick change to a different branch

* Change destination branch

* Set-up CI with single and combined votes

[...]

We already have some of the above but there are a lot of place for improvements.

> I have never heard any complaints that this name is
> confusing. I'm working with Gerrit for 5 years now.

Sorry, consider my complaint registered above.

Sorry Martin, I'm not convinced at all, and I don't think this one

single complaint is enough to throw out of the window the major

part of Gerrit mindset, and cause such a mess and migration pain

on all levels (see the list above). (Can't you rename whatever you

think will help your users in your own Gerrit fork and keep away

that mess and migration pain from upstream?).

 

> I think that project is the right name, for number of
> reasons:
>
> * Project in Gerrit conceptually is much more then just
> Git repository. Permisions are fundamental Gerrit feature
> and the Gerrit poject is where the persmissions are
> configured, by defining the project ACLs with project
> inheritance scheme. That way, the project in Gerrit is
> Git repository + meta data. We should do a better job in
> gerrit documentation and explain to the users, what the
> project is and why it is not just called repository: it's
> more than that.

While these are all true statements, I feel that nothing is
fundamentally lost by using the term Repository.  People
think of a project as the git information and could care
less that the repository happens to also store additional
Gerrit info in it.  When I clone --mirror a gerrit project
to my local disk, do I end up with a project or a
repository?

One complaint I often hear from gerrit administrators is that replication

configuration is to complex. I always wanted to fix that, by allowing

replication configuration on Gerrit poject configuration page. That way

we wold even abandon 1-to-1 relationship between Project and Repository.

On the project page, we would have then:

Project: foo

Primary git repository: foo.git

Mirror_1: bar.git

[...]

Mirror_n: baz.git

 

> * Consistency with abstract terms in Gerrit: Why you
> havn't suggested to rename the term "change" to "commit"?

A change does not equate to a commit, a commit equates to a
change patchset.  That being said, a better term for change
should be considered if there is one.  But a change does do
a pretty good job explaining what it is.  Is there a better
git term?

"Change" is wrong and confusing term for pre-submit review workflow

tool. By uploading a CL to a refs/for/foo branch you don't change anything.

You ask, send a request to projects maintainers to review and merge/submit

your CL. Thus the appropriate name would be:

Change request

Review request

Merge Request

Submit Request

Now, that we opened gerrit for post submit review workflow, we could also

differentiate those workflows and start to add what kind of workflow was used,

by prepending it to the review request name:

Pre-submit review request

Post-merge review request

But then again, this would cause similar migration pain without any benefits.

> * Open Gerrit Code Review for other (D)VCS backends. Today
> gerrit only supports Git, but
> conceptually, Gerrit can be opened for other backend
> systems in the future. What if the name for other
> backends is different as it's in Git? Would we rename to
> more abstract name Project back again?

Imagine that we started out with the term repository and
then we added a DVCS with some other term for its
repository.  At that point we might look for another term
like "Project", but along the way I think we would all
think, "ugh this sucks having to come up with a term that
isn't as obvious and clear to new users as what the DVCSes
use"?    Maybe we would just stick with the specific terms
for each DVCS to make it clear?

That wouldn't fly, as we wouldn't want (at least /me) to change

plugin API, URL scheme, SSH command Interfaces for projects

that are using different (D)VCS backends. Example, even if it is

called VOB (virtual object base) in another tool, it should use

exactly the same "project" in URL scheme.

 

> * Wrong time frame/Migration of ReviewDB->NoteDb/PG -> GWT
> UI is underway:

I am not involved enough upstream to be able to comment on
this, and I respect your points about it possibly not being
a good time,

@Logan, Patrick:

Nobody was saying, to change everything in the same time. I just wanted

to understand where the motivation is coming from, before jumping into the

cold water and starting to change everything in the code base. And yes, I

strongly believe that we should avoid over-hasty actions, and thoroughly

think through the first and the next steps for all changes with highly impact

on the thousands of gerrit sites in the wild. The approach "let us do s/foo/bar/g

and then see what are the next steps", just doesn't fly in this context. I expect

a plan, vision, ideas for the next moves before merging first change of any highly

impact change series. I also think, that this project would greatly benefit from

product manager role.

Overall I see this whole bikeshedding as a big confusion. There are non-justified

assumptions (sorry, I'm still missing any proof of those claims), the gerrit users 

do have problem with "project" term. Any over-hasty actions: "Let's change

everything and then think what to do next"- approach.

The whole discussion resembles me strongly that never ending bikeshedding story

we had years ago, about naming of "Submit" button. That button was changed back

and force from Submit to Merge and then back to Submit. Luckily, this mistake,

didn't have such severe consequences on all gerrit installation in the wild, like your

current proposal, and those renames were reverted, but the shitstorm and bikeshedding

did not stop.

So, the question was: how can we stop all that bikeshedding and keep it away

from our issue tracker and the yo-yo commit/revert game from our code base, while

still preserving the backward compatibility and thus avoiding any negative impact on

current gerrit user base? You find my pragmatic answer to the above problem that

satisfies all the above requirements in gerrit documentation:

[[change.submitLabel]]change.submitLabel::

+

Label name for the submit button.

+

Default is "Submit".

After I did that, we had never again this discussion. But please note,

neither (!) REST API, nor (!) SSH command, nor code base (!) was changed. 

That's because gerrit users are mostly divided in three roles:

* 1. simple users,

* 2. administrator

* 3. plugin/extension developers

The first role (mostly) do not have any contact with plugin API, URL scheme,

and even (?) SSH commands, so that preserving the term "Submit" there,

but still naming the button in the UI Mickey Mouse, is not a contradiction for them.

So my suggestion would be similar in this bikeshedding discussion.

My suggestions in order of my preferences: 

1. There is no unconditional rename of any major gerrit term with the suggested

scope: change everything, with such high impact on gerrit installations and mess

in the code base (duplication in plugin API for backwards compatibility) invalidation

of all gerrit teaching material, videos, tutorial, blogs and books.

2. If you think that your users would benefit from any rename, do it in your fork,

and keep that mess away from upstream.

3. Reduce the scope of your proposal: Currently suggested scope:

* Change the PG-UI
* Change (to be removed) GWT-UI?
* Change URL scheme (again)
* Change all refs/meta/config files from project.config to repository.config for core and plugins
* Change plugin API (with requirements to adapt all plugins, that need to be adapted to PG UI first)
* Rename All-Projects to All-Repositories,
* Rename plugins from delete-projects to delete-repository

* Rename project predicate to repository predicate in changes secondary index

* Rename project secondary index to repository secondary index

* Rename project parameter in all SSH commands

...

new scope:

* Add new configuration options (I would rather avoid yet another obscure

configuration options, because we already have to much of them, but this

is much, much less mess, disruption and pain as the suggested scope):

[[change.projectLabel]]change.projectLabel::

[[change.changeLabel]]change.changeLabel::

[[change.patchSetLabel]]change.patchSetLabel::

[...]

[[put-here-any-further-rename-you-think-your-users-would-benefit-from]]...::

Per default, all those labels should stay how they called today, obviously, and there

is no disruption for current gerrit installations.

Only one thing is affected by this configuration and nothing else:

* PG-UI

3. If you still not convinced, and think we should unconditionally rename any major

gerrit term, then I expect a broader community participation/discussion on that move,

and have agreement of gerrit community on detailed DRAFT proposal (like we did in

WIP workflow):

* Problem statement with detailed justification (and no, a statement "i *assume* it improve

  the life of everyone" is not a justification, a representative poll would be very useful)

* Suggested solution

* Impact

* Transition period

* Time Frame

* Backwards compatibility considerations

* Alternatives considered

[Sven Selberg]

Hi,

I agree with David O.

1. Gerrit project is a meta entity that is not confined to a git repository.

    * Even when completely migrated to Note DB you still don't get the whole project by cloning the git.

      There are always (with the possible exception of All-Projects) references outside the git repository

      to other git repositories that contain the access rights for inherited projects.

    * In the project configuration there are references to users defined in a different git (or DB).

    * A git repository is no longer a Gerrit project once you remove it from the Gerrit context,

2. Changing the name would IMO not solve any, or at least not reduce the amount of, problems. 

    * Since in this context "repository" is just as general and ambiguous as "project", the net sum of confusion

      would be the same, only slightly shifted towards another domain.

3. There are no clear benefits to changing the name.

    * "git repository" is often interchangeable with "git project".

        ( see f.i. https://git-scm.com/book/en/v2/Appendix-C%3A-Git-Commands-Getting-and-Creating-Projects).

       So if you feel that the fact that most of what a Gerrit project is lives in a git repository should be

       reflected in the label (I don't necessarily think that) that is already true for the term "project".

4. Changing the name would _add_ to the confusion and problems.

    * An accepted and widespread terminology has a very long life-span, far beyond the end-date of what the

      terminology originally described, and are often used to describe other, similar, phenomena in different

      domains.

      ( An android tablet is more often than not referred to as a "pad" by a large percentage of the population.

      Googlers insists on calling a change a CL. etc. etc.)

      With that in mind you can be fairly certain that  the majority of Gerrit devs, admins and users will, to

      a large extent, continue to refer to, what is now known as a, Gerrit project as a "Gerrit project" years

      after we switch to "Gerrit repository". This would only _increase_ the confusion felt by newcomers to Gerrit.

To conclude. The term "Gerrit project" has it's downsides but it is well established and it works. It is a good

description of the entity it is designed to describe. Changing the name to something that IMO is not better

would only result in cost with very little or no benefit.

/Sven

P.s.

I think "change" is a spot-on term for a change. Since it _is_ a change (to the codebase, the behavior...) ,

and the different patchsets are different versions of that change. A "change" can be uploaded without

the intention of ever being integrated to any  branch but it is still a change. A Gerrit "change" to me lives

more on the meta-level, it's an idea of a "change" realized in the patchset(s) of the change. I think it is

helpful to think of it that way, and that is what I use when I try to explain what a Gerrit change is to new

users.

[Saša Živkov]

Yes. Maybe not because All-Projects is such an intuitive name but because this name is well

known in Gerrit community in the meantime :-)

 

When I say all repositories,

what is that? Today if I say: project config. It's clear that I mean gerrit project

configuration file on refs/meta/config branch. If I say repository config what do

I mean? Gerrit repository config file on refs/meta/config branch or Git's own

repository config file?

 

Indeed. These are valid points IMHO.

The existing terminology is not perfect, but the proposed new terminology also

brings its own set of issues. Even if we do not count all the necessary

migration effort, the benefits of the new terminology do not seem to significantly

overweight its disadvantages.

 

--
--
To unsubscribe, email repo-discuss+unsubscribe@googlegroups.com

More info at http://groups.google.com/group/repo-discuss?hl=en

---
You received this message because you are subscribed to the Google Groups "Repo and Gerrit Discussion" group.

To unsubscribe from this group and stop receiving emails from it, send an email to repo-discuss+unsubscribe@googlegroups.com.

[Saša Živkov]

On Thu, Feb 22, 2018 at 9:54 AM, David Ostrovsky <david.o...@gmail.com> wrote:

This is unrelated to the topic of this discussion. Everyone of us made or will make

a wrong assessment in our code reviews, but this shouldn't imply that other

assessments of that person are wrong.

To cite Niels Bohr:

“An expert is a person who has made all the mistakes that can be made in a very narrow field.”

 

[David Ostrovsky]

Yes, you are right. I apologize for saying that. My point was the consequences, not

the mistake.

 

[chor...@wikimedia.org]

On Thursday, February 22, 2018 at 12:54:50 AM UTC-8, David Ostrovsky wrote:

You are trying to solve a problem that doesn't exist. Gerrit users don't have a problem

of understanding of Gerrit Project/Git Repository terms.

This. A million times this. In my 6 or so years of administering Gerrit at Wikimedia, "Project" vs

"Repository" has never once been mentioned to me as a point of confusion. I'll also note that

we have a lot of volunteers across many different countries who contribute so we've got a far

more representative sample of skillsets and language abilities in our environment.

There's a ton of things that are confusing/difficult about Gerrit for new users. David points to a lot

of them. Let's focus on that instead of continuing to paint this bikeshed a slightly different shade

of green.

-Chad

[Jonathan Nieder]

Hi,

David Ostrovsky wrote:

I believe that Gerrit founder made very wise and conscious decision and

preferred to separate those two concerns to avoid the ambiguity and collision

between Gerrit project and Git repository. Term Repository is very much

overloaded in DVCS domain in general and in Git in particular. Keeping

a different name clearly reduces the scope in discussion and avoids confusion.

Not that it's too relevant, but just for completeness:

I had the conversation with Shawn about why Gerrit calls repositories projects in person multiple times. The answer was simple: it inherited the name from Rietveld, which was a VCS-agnostic tool. The natural followup question: if he could do it over, would he call it "repository"? IIRC the answer was "maybe".

I've also more than once seen a conversation where the term "project" led to confusion, since it's ambiguous. It is not that people mistook projects for repositories, whatever that would mean. It is that when someone said project, another person didn't know whether they meant a project like Android, or a project like improving Android's battery life, or a Gerrit project like platform/frameworks/base on android-review.googlesource.com. Clarifying that they meant "a Gerrit project" cleared up the confusion.

Hope that helps,

Jonathan

[Patrick Hiesel]

Thank you for this discussion. I see that emails get longer and longer which makes it harder to follow the individual points that people are making.

I'd like to propose to take a different direction in this discussion by taking it to the next hackathon and have it in-person instead. We can dial people in that don't participate in-person so that nobody is left behind.

I definitely agree to the point that David O made: We should make sure we understand all aspects of this change, as well as it's impact and motivation. I would therefore use the time until then to compile all the arguments that came out of this email thread into a document and invest more into presenting impact and motivation.

Thanks,

Patrick

--
--
To unsubscribe, email repo-discuss...@googlegroups.com

More info at http://groups.google.com/group/repo-discuss?hl=en

---
You received this message because you are subscribed to the Google Groups "Repo and Gerrit Discussion" group.

To unsubscribe from this group and stop receiving emails from it, send an email to repo-discuss...@googlegroups.com.

[Patrick Hiesel]

Hi there,

as announced earlier I would like to discuss this at the hackathon this week and would propose tomorrow, Thursday April, 19 at 5pm CET.

If anyone who is not at the hackathon would like to take part in the discussion, please let me know and I'll dial you in.

Thanks,

Patrick

On Thursday, March 1, 2018 at 2:42:22 PM UTC+1, Patrick Hiesel wrote:

Thank you for this discussion. I see that emails get longer and longer which makes it harder to follow the individual points that people are making.

I'd like to propose to take a different direction in this discussion by taking it to the next hackathon and have it in-person instead. We can dial people in that don't participate in-person so that nobody is left behind.

I definitely agree to the point that David O made: We should make sure we understand all aspects of this change, as well as it's impact and motivation. I would therefore use the time until then to compile all the arguments that came out of this email thread into a document and invest more into presenting impact and motivation.

Thanks,

Patrick

On Tue, Feb 27, 2018 at 6:31 AM 'Jonathan Nieder' via Repo and Gerrit Discussion <repo-d...@googlegroups.com> wrote:

Hi,

David Ostrovsky wrote:

I believe that Gerrit founder made very wise and conscious decision and

preferred to separate those two concerns to avoid the ambiguity and collision

between Gerrit project and Git repository. Term Repository is very much

overloaded in DVCS domain in general and in Git in particular. Keeping

a different name clearly reduces the scope in discussion and avoids confusion.

Not that it's too relevant, but just for completeness:

I had the conversation with Shawn about why Gerrit calls repositories projects in person multiple times. The answer was simple: it inherited the name from Rietveld, which was a VCS-agnostic tool. The natural followup question: if he could do it over, would he call it "repository"? IIRC the answer was "maybe".

I've also more than once seen a conversation where the term "project" led to confusion, since it's ambiguous. It is not that people mistook projects for repositories, whatever that would mean. It is that when someone said project, another person didn't know whether they meant a project like Android, or a project like improving Android's battery life, or a Gerrit project like platform/frameworks/base on android-review.googlesource.com. Clarifying that they meant "a Gerrit project" cleared up the confusion.

Hope that helps,

Jonathan

--
--

To unsubscribe, email repo-discuss+unsubscribe@googlegroups.com

More info at http://groups.google.com/group/repo-discuss?hl=en

---
You received this message because you are subscribed to the Google Groups "Repo and Gerrit Discussion" group.

To unsubscribe from this group and stop receiving emails from it, send an email to repo-discuss+unsubscribe@googlegroups.com.

[Luca Milanesio]

Hi Patrick,

unfortunately I did not manage to come over :-(

However, will be more than happy to attend remotely: are you going to setup a Hangout?

Luca.

To unsubscribe, email repo-discuss...@googlegroups.com

More info at http://groups.google.com/group/repo-discuss?hl=en

---
You received this message because you are subscribed to the Google Groups "Repo and Gerrit Discussion" group.

To unsubscribe from this group and stop receiving emails from it, send an email to repo-discuss...@googlegroups.com.

[Patrick Hiesel]

Hi Luca,

yes, I'll set up a hangout and invite you by your Gmail address.

In case there are more people who want to join, please just let me know (you can also email me directly with the address that you want to be dialed in).

Thanks!

Patrick

Luca.

To unsubscribe, email repo-discuss...@googlegroups.com
More info at http://groups.google.com/group/repo-discuss?hl=en

---
You received this message because you are subscribed to the Google Groups "Repo and Gerrit Discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to repo-discuss...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[lucamilanesio]

*UPDATE* Because of the massive move of Repos and shift from GitHub to GitLab ... to we want to rethink about our decision to rename Gerrit Projects to Gerrit Repositories?

In GitLab, the repositories are actually referred to as "Projects" :-O

Luca.

Luca.

To unsubscribe, email repo-disc...@googlegroups.com