mesos-reviews mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Benjamin Bannier <benjamin.bann...@mesosphere.io>
Subject Re: Review Request 67308: Documented how to setup and use cquery with Mesos.
Date Mon, 28 May 2018 07:15:42 GMT


> On May 25, 2018, 9:35 p.m., Benjamin Bannier wrote:
> > docs/developer-guide.md
> > Lines 128 (patched)
> > <https://reviews.apache.org/r/67308/diff/1/?file=2029074#file2029074line128>
> >
> >     Thanks for capturing this!
> >     
> >     As a high level comment, I believe this doc should capture important information
for developing Mesos. Since it already is pretty big I am not sure this new section is of
enough general importance to be included here. Maybe we could move it to a blog post or additional
document linked under `Further reading` at the bottom instead?
> 
> Andrew Schwartzmeyer wrote:
>     > I believe this doc should capture important information for developing Mesos.
Since it already is pretty big
>     
>     As the sole author of this document so far, I appreciate that!
>     
>     > I am not sure this new section is of enough general importance to be included
here.
>     
>     I respectfully disagree with this. I am quite sure it is of enough general importance,
as navigating the Mesos code-base as an incredible chore, and the majority of devs I've spoken
with just fall back to inefficient uses of `grep`. Based on the feedback of my cquery demo
at the last dev sync, I think this information is wanted, and I don't see a better place than
a developer guide.
>     
>     How strongly do you feel that we should split this document up?

Imagine being a new contributor to Mesos wanting to know how to write code and contribute
their patch. They could read `developer-guide.md` for e.g., best practices or patterns, `c++-style-guide.md`
for how to format their code, and `[beginner|advanced]-contribution.md` for how to contribute
their code.

Currently all these documents already ask for a lot of reading, even though they just contain
information which should apply to almost everyone. Ideally a contributor should know everything
in these guides. This is asking a lot from a new contributor, and I think it is important
to focus on highly relevant information. Documenting less central information is still great,
but we should avoid overloading documents we would point new contributors to -- we can always
add these elsewhere.

As an example, I am pretty happy having integrated Mesos' `clang-tidy` with vim's `ale` plugin,
but I think putting this into a doc new contributors would reach out for to make sense of
Mesos wouldn't be a great experience for them.


- Benjamin


-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://reviews.apache.org/r/67308/#review203902
-----------------------------------------------------------


On May 25, 2018, 4:30 a.m., Andrew Schwartzmeyer wrote:
> 
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> https://reviews.apache.org/r/67308/
> -----------------------------------------------------------
> 
> (Updated May 25, 2018, 4:30 a.m.)
> 
> 
> Review request for mesos, Benjamin Bannier, Benjamin Hindman, Benjamin Mahler, Greg Mann,
Jie Yu, James Peach, and Joseph Wu.
> 
> 
> Repository: mesos
> 
> 
> Description
> -------
> 
> Note that while cquery and LSP support many editors, this only
> demonstrates how to setup Emacs. Documentation on Vim setup is
> welcome!
> 
> 
> Diffs
> -----
> 
>   docs/developer-guide.md 3dbc93ee4225abc54593dda005781d879d2ca8da 
> 
> 
> Diff: https://reviews.apache.org/r/67308/diff/1/
> 
> 
> Testing
> -------
> 
> 
> Thanks,
> 
> Andrew Schwartzmeyer
> 
>


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message