reef-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mariia Mykhailova <>
Subject RE: Improving dev experience for REEF .NET
Date Fri, 15 Jan 2016 20:27:34 GMT
A couple of comments:

>> b. Documentation for new features. What should be the process?
> However, that documentation is currently largely in vain, as we haven't found a way to
generate a nice website from it like we do on the Java side.

REEF-113, easy to do if we're willing to use external tools for site generation. I've just
tried to configure Doxygen (, free open-source), and
it produces a very similar site with very little configuration effort. I have several questions
about appearance of the website, will ask in JIRA. 

>> 3. Build flakiness 4. Test coverage

Yes, we need to put more emphasis on test quality.
Right now we have two ongoing issues with existing tests, REEF-1079 which I'm looking at,
and REEF-1040 which is pretty much abandoned.


-----Original Message-----
From: Markus Weimer [] 
Sent: Thursday, January 14, 2016 6:13 PM
Subject: Re: Improving dev experience for REEF .NET

thanks for putting these together!

On 2016-01-14 17:17, Anupam wrote:
> 1. Stable APIs a. Tagging new API which could change frequently b.
> API spread too thin across assemblies c. Accidentally public APIs and 
> their deprecation

We are acting on those, right? Once REEF-1087 is completed, we should be in much better shape
in terms of making only the real APIs `public`.
That in turn should enable us to act on the assembly structure.

> b. Documentation for new features. What should be the process?

There are two levels of documentation: API docs and prose on that what and why of a new feature.
I think we should absolutely have API docs for every `public` interface, class and method.
However, that documentation is currently largely in vain, as we haven't found a way to generate
a nice website from it like we do on the Java side.

Regarding tutorials and such, we are doing badly. Some work has been done, but this clearly
can be improved. Not sure how to make the time for that, though. Everybody agrees that we
*should* do something, but feature work seems to get in the way of that pretty reliably.

> d. Example code should be exemplary 3. Build flakiness 4. Test 
> coverage

+1 on each of them.

All of these are "easy" fixes. We know how this should be done, we just haven't.

> 5. Pull request process

This is the thorny one. Like most Big Data projects in Apache, we've decided on a review-then-commit
(RTC) workflow, which means every contribution needs to somehow motivate a committer to review
Further, we somehow need to agree amongst the committers on review standards. Both of these
`somehow` statements are extremely tricky in practice.

> b. (Subjective) Lack of process for unstable APIs along with PR 
> turn-around time (sometimes) makes me wary of splitting work into 
> small PRs.

What should we do beyond annotating that code with `[Unstable]`?

PR turn-around time will always be dependent on the load on the committers, unless we decide
to ditch RTC for CTR. If we do that, the work of the release manager becomes more substantial:
They'd have to orchestrate several rounds of cleanups before the release can be cut. 
Other projects do that, so it isn't out of the question.

> Make a separate project named something like 
> Org.Apache.REEF.SDK/Org.Apache.REEF.APIs which has all the supported  
> stable and public APIs. [...] Consumption: Split NuGets into SDK and  
> Runtime (absolute minimum to run a REEF app) packages. IMRU and such  
> applications can have their own NuGets.

+1, with one change: We need one each for REEF, Wake, Tang.

One issue I see with this is that we either have to rename all types again or have to have
projects where the DLL, NuGet and default namespace all have different names.

> Build flakiness: Use IDE features as much as possible. Minimize 
> manually changing build files as much as possible. Clean up 
> build.props to not have Targets but just have aliases. Remove hidden  
> common operations done via build.props across multiple project builds, 
> this makes us susceptible to build concurrency issues.

+1, this is a bug and really shouldn't need a list discussion to drive
consensus. Feel free to file JIRAs.

> Test coverage: Mandating addition of unittests for all new code added. 
> Add E2E tests, run them on localruntime as well as one box setup of 
> YARN (Mesos?). We need to add stress tests.

[REEF-111] captures the infrastructure aspects of this. I believe Mariia is looking into it.
Regarding the mandate for new tests: This will be tricky to enforce, as we have plenty of
"trivial" code changes flying by. Asking for tests in addition to those would likely slow
us down. For new features, I am all with you. Which brings us back to the question of how
to set common expectations for PR reviews.

> Pull request: We need to come up with PR guidelines

Please have a look at our contributors guide and improve as you see fit:

So far, the coding guidelines are a straight copy from CoreFx, with the added emphasis on
immutability in REEF.

View raw message