> 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 > >
