bug#41572: 28.0.50; [PATCH] Support plain project marked with file .emacs-project

[Dmitry Gutov]

On 26/11/22 16:27, Eli Zaretskii wrote:
> > Date: Sat, 26 Nov 2022 15:22:36 +0200
> > Cc: philipk@posteo.net, rudi@constantly.at, eric@ericabrahamsen.net,
> >   cjpeople2013@gmail.com, theo@thornhill.no, mardani29@yahoo.es,
> >   salutis@me.com, joaotavora@gmail.com, manuel.uberti@inventati.org,
> >   juri@linkov.net, arstoffel@gmail.com, 41572@debbugs.gnu.org
> > From: Dmitry Gutov <dgutov@yandex.ru>
> >
> > On 26/11/22 09:47, Eli Zaretskii wrote:
> >
> > > > +(defcustom project-vc-extra-root-markers nil
> > > > +  "List of additional \"markers\" to signal project roots.
> > > > +
> > > > +A marker is either a base file name or a glob pattern for such.
> > > > +
> > > > +These will be used in addition to regular directory markers such
> > > > +as .git, .hg, and so on, dependent on the value of
> > > > +`vc-handled-backends'.
> > >
> > > "These will be used" how?  This crucial information is sorely missing from
> > > this description.  Likewise, how "markers" that are not files are used and
> > > are useful?
> >
> > Not files, meaning, markers which are globs with wildcards?
> >
> > > >                           They are most useful when a VC project
> > > > +has subdirectories inside it that need to be considered as
> > > > +separate projects, but still use the parent's ignore rules and
> > > > +general behaviors.
> > >
> > > How are "markers" useful in this scenario?
> >
> > As mentioned in e.g.
> > https://debbugs.gnu.org/cgi/bugreport.cgi?bug=54228#11, monorepos often
> > contain subdirectories which one might want to handle separately.
> >
> > Those subdirectories often come in standard structures, e.g. a frontend
> > subdirectory might contain a file called "package.json", a backend
> > subdirectory might contain "Gemfile" or "build.gradle", or perhaps
> > "autogen.sh", and so on.
> >
> > Adding those to the markers list will tag those subdirectories as
> > projects on their own. People can also use the file names special to
> > their particular organization instead of those above.
> >
> > > > +It can also be used for projects outside of VC repositories.
> > > > +Their behavior will still obey the relevant variables, such as
> > > > +`project-vc-ignores' or `project-vc-name'."
> > >
> > > And in this one?
> >
> > This covers the use cases described in the first messages of this and
> > the merged bug report:
> >
> > https://debbugs.gnu.org/cgi/bugreport.cgi?bug=41572#5
> > https://debbugs.gnu.org/cgi/bugreport.cgi?bug=54228#5
> >
> > People would add ".project" or ".emacs-project" to
> > project-vc-extra-root-markers and see things work.
> >
> > Might have to restart Emacs, though, if they already called project
> > commands in the given directory, because the current project info is cached.
> >
> > > IOW, please describe the main ideas of this approach instead of relying on
> > > use immediately gleaning that from a patch with incomplete documentation.
> >
> > If you have further questions, please ask.
>
> Thanks, but I meant for at least some of the above to be in the doc strings
> and/or explained here in plain English.  Readers aren't supposed to search
> bug reports for relevant information.  (And for me personally, this means I
> won't be able to look up the relevant information before at least another
> week or two, which is a pity.)

The links were meant to illustrate that most people Cc'd probably 
understand the context already (modulo some forgetting because time has 
passed).

And either way I'm probably too close to the problem to understand 
easily what is clear to the average user and what is not. That's why 
questions are always useful.

I've added the examples to the docstring and rephrased it a little. Does 
it read better now?

project-vc-extra-root-markers-v2.diff
Description: Text Data