[clangd-dev] [llvm-dev] Subprojects, GitHub, and the Monorepo

[Sam McCall via clangd-dev]

> And I think we should do much of this on GitHub, rather than *.llvm.org.
And not in the upcoming monorepo, but in a separate repository. (e.g.
github.com/llvm/clang)
Of course, I meant github.com/llvm/clangd here.

On Sun, Oct 21, 2018 at 12:16 AM James Y Knight <jyknight at google.com> wrote:

> I think these issues you raise are all basically fixable, without
> fragmenting the community.
>
> # Bugtracker
>
> Yes, everyone has a github account -- but I think everyone could also use
> bugzilla easily enough, if we add a "Login with github" button. I would
> like someone to volunteer to work on getting bugzilla patched with that
> functionality. (Someone, please volunteer!)
>
This is a necessary improvement, but not a sufficient one:
 - our users still won't know how to use bugzilla
 - bolted-on github account support is second-class (e.g. cc lists are
still email addresses, @mentions don't work)
 - bugzilla's UI is atrocious (hard to summarize; happy to go into this if
there's real disagreement)
 - it's not feasible to run an instance per subproject, so e.g. subprojects
have no ability to define their own labels/keywords

# Website, and raw HTML vs markdown.
>
> Clangd doesn't have a website now, in the same sense as clang, llvm and
> other llvm projects do. It just has a little bit of sphinx documentation
> hidden deep within clang's docs. I think this is a large part of the
> frustration you raise, but it's not a necessary part of living under the
> llvm project umbrella. I think you probably want to make clangd have its
> own actual landing page.
>
> As for the authoring format, IMO it's definitely a good idea to start
> migrating to using markdown for the website, and migrate to github pages
> autogeneration and hosting. (But I think that should be done project-wide,
> not one-off.)
>
This all sounds right. A separate landing page is the right thing. Having
spent some time attempting this, I would certainly like avoid sphinx
(including its markdown plugns).

Can you elaborate on why this should be done all in one go? Currently the
various top-level sites are basically islands, and seem well-suited for
piecemeal migration.
And for projects adding new documentation, forcing a choice between
investing in a dead-end and migrating the world feels... unpleasant.

# Exposing LLVM community identity
>
> Clangd is part of the LLVM community, and having a community identity can
> be a good thing. But, indeed, the projects should also have their own
> identities within that.
>
> You've expressed "Users don't want to know that clangd is part of the llvm
> community". But I think that's exactly wrong. We _should_ be exposing that
> fact and pushing that identity, and I don't think that, by itself, bothers
> any uesrs.
>
Certainly the website needs to say "clangd is built on Clang, and is part
of the LLVM project".

But there shouldn't be any natural path from clangd landing page to "all
LLVM bugs" (other than explicitly clangd -> llvm -> bugs).
That does indeed bother users.

If you look at lldb.llvm.org, the "bug reports" link links to LLVM
bugzilla. Same for LLD.
clang-analyzer links to enter_bug.cgi?product=clang. The natural path to
seeing all bugs is clicking "home" or "browse", which takes you to all LLVM
bugs.
These are not coincidences, this is the fundamental navigation structure,
and patching it only makes it more confusing.

However, I think I see a different underlying issue hiding in that stated
> concern: finding clangd in the current website is too confusing. Having
> clangd be part of the LLVM community -- or part of the LLVM website --
> isn't the issue problem. Having clangd not be _easily accessible_ on the
> LLVM website is a problem.
>
I disagree here. Our audience isn't people browsing around llvm.org, it's
people typing "clangd" into google, and the (limited) docs are the top
result.
The problem is getting lost once you're there.

# Path forward
>
As described above, I don't think the path described actually addresses the
problems that clangd has.
It seems like a reasonable direction for parts of the project that are
well-served by the current structure, though.

Brian Cain wrote:
> Can't we / shouldn't we create decomposed repos by partitioning commits
made to the monorepo into corresponding ones made to per-project repo
"mirrors"?
> ...
> Not sure which "users" we're referring to but if we're talking about ones
who use only binaries provided by llvm project, they wouldn't necessarily
have to know or care anything about git, svn, github, development trees, or
anything else.

This thread is about the website, documentation, bugtrackers etc.
Binary-only users care about those.
I think the source-layout topics have been pretty well covered elsewhere.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/clangd-dev/attachments/20181021/47f51431/attachment.html>