We had considered what Benjamin proposes (I think I even wrote the code to do it), but we decided it was better to commit them back since all of the other documentation is in the docs folder and is checked in. I don't have a strong opinion either way though, so I'm fine with not commtting them back in the future.
On Mon, May 23, 2016 at 3:48 PM, Benjamin Mahler <bmah...@apache.org> wrote: > +kevin for context > > When we approached this problem there were a few routes we could take. One > approach we were leaning towards was to allow the help information to be > specified directly in markdown rather than in C++. Markdown would be the > only source of help information, and the C++ code calling route() would > point libprocess to the markdown file. Or it would be "burned in" to the > C++ source via tooling during the build process. There were some tradeoffs > with this approach: > > + single source of help information, no need for "generating" it > + easy to discover and read help information by navigating the project, > it's in markdown only, don't need to read C++ source > - not as easy to enforce a standard help markdown format > - need to bundle more "assets" with the code (unlike mesos, libprocess > currently has no assets that need bundling so this is new territory), > because at run time we need access to the markdown files to serve them > > I'm not sure we considered your approach Benjamin, which sounds like a > small tweak to the current approach: > > (1) Continue writing help information in C++. > (2) Keep existing tooling we built for obtaining help markdown from the > binaries. > (3) Run this tooling during the build and output into the build directory > (these do not get checked in). > (4) As part of the manual website update, do a build and publish the > generated markdown. > > I think the only reason we avoided this approach was that we wanted the > help information to be easily discoverable in the project source (i.e. > docs/endpoints rather than scattered across C++), but I suppose the > argument here is that for now the users can just use the website instead. > Sounds ok to me. > > On Wed, May 18, 2016 at 4:01 AM, Alex Rukletsov <a...@mesosphere.com> wrote: > >> Thanks Neil. Pushed 54339eb0e934e120e5cb5e693681679dea24b2d2. It also >> includes an update induced by slave->agent rename. >> >> I think we eventually should do what Benjamin suggests. It's hard for a >> human to remember, when a certain script should be run (even though having >> a script is a huge improvement already). >> >> On Wed, May 18, 2016 at 11:53 AM, Benjamin Bannier < >> benjamin.bann...@mesosphere.io> wrote: >> >> > Hi, >> > >> > the way one currently has to manually regenerate markdown outputs which >> > should then be checked in together (and ideally: atomically) with the >> > corresponding source changes seems to be a reoccurring source of >> friction. >> > >> > I understand that being able to e.g., reference the generated markdown >> > outputs is useful, but believe the fundamentally right thing to do would >> be >> > to generate the markdown outputs as part of the build and *not check them >> > into source control*. If one would need to reference the endpoint help >> one >> > could e.g., use links to >> > https://mesos.apache.org/documentation/latest/endpoints/ and children. >> > >> > Any reason this isn’t what we are already doing? >> > >> > >> > Cheers, >> > >> > Benjamin >> > >> > >> > > On May 18, 2016, at 11:42 AM, haosdent <haosd...@gmail.com> wrote: >> > > >> > > Is it possible to show a warning in `./support/mesos-style.py` when >> > commit >> > > changes contains "src/master/http.cpp" or "src/slave/http.cpp" while >> > > doesn't contain document changes? >> > > >> > > On Wed, May 18, 2016 at 5:06 PM, Neil Conway <neil.con...@gmail.com> >> > wrote: >> > > >> > >> When modifying the endpoint help text, we should remember to update >> > >> the generated help files (via support/generate-endpoint-help.py) -- >> > >> the changes to both the input text and generated output files should >> > >> be included as part of the same commit. >> > >> >> > >> Neil >> > >> >> > >> On Wed, May 18, 2016 at 10:58 AM, <m...@apache.org> wrote: >> > >>> Repository: mesos >> > >>> Updated Branches: >> > >>> refs/heads/master a7835f889 -> 9f63d95f3 >> > >>> >> > >>> >> > >>> Updated quota endpoint help. >> > >>> >> > >>> >> > >>> Project: http://git-wip-us.apache.org/repos/asf/mesos/repo >> > >>> Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/9f63d95f >> > >>> Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/9f63d95f >> > >>> Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/9f63d95f >> > >>> >> > >>> Branch: refs/heads/master >> > >>> Commit: 9f63d95f3cac17c94a7aff57980478263c78f6ee >> > >>> Parents: a7835f8 >> > >>> Author: Adam B <a...@mesosphere.io> >> > >>> Authored: Wed May 18 01:56:57 2016 -0700 >> > >>> Committer: Adam B <a...@mesosphere.io> >> > >>> Committed: Wed May 18 01:57:52 2016 -0700 >> > >>> >> > >>> >> ---------------------------------------------------------------------- >> > >>> src/master/http.cpp | 11 ++++++++--- >> > >>> 1 file changed, 8 insertions(+), 3 deletions(-) >> > >>> >> ---------------------------------------------------------------------- >> > >>> >> > >>> >> > >>> >> > >> >> > >> http://git-wip-us.apache.org/repos/asf/mesos/blob/9f63d95f/src/master/http.cpp >> > >>> >> ---------------------------------------------------------------------- >> > >>> diff --git a/src/master/http.cpp b/src/master/http.cpp >> > >>> index c4ca343..5d73a1d 100644 >> > >>> --- a/src/master/http.cpp >> > >>> +++ b/src/master/http.cpp >> > >>> @@ -1286,15 +1286,20 @@ string Master::Http::QUOTA_HELP() >> > >>> { >> > >>> return HELP( >> > >>> TLDR( >> > >>> - "Sets quota for a role."), >> > >>> + "Gets or updates quota for roles."), >> > >>> DESCRIPTION( >> > >>> - "Returns 200 OK when the quota has been changed >> > successfully.", >> > >>> + "Returns 200 OK when the quota was queried or updated >> > >> successfully.", >> > >>> "Returns 307 TEMPORARY_REDIRECT redirect to the leading >> master >> > >> when", >> > >>> "current master is not the leader.", >> > >>> "Returns 503 SERVICE_UNAVAILABLE if the leading master cannot >> > >> be", >> > >>> "found.", >> > >>> + "GET: Returns the currently set quotas as JSON.", >> > >>> + "", >> > >>> "POST: Validates the request body as JSON", >> > >>> - " and sets quota for a role."), >> > >>> + " and sets quota for a role.", >> > >>> + "", >> > >>> + "DELETE: Validates the request body as JSON", >> > >>> + " and removes quota for a role."), >> > >>> AUTHENTICATION(true), >> > >>> AUTHORIZATION( >> > >>> "Using this endpoint to set a quota for a certain role >> requires >> > >> that", >> > >>> >> > >> >> > > >> > > >> > > >> > > -- >> > > Best Regards, >> > > Haosdent Huang >> > >> > >> -- ~Kevin
