Ideas for contributions

[sergeybykov]

We added a page with some initial ideas for contributions. Let's use this issue for discussing the list and adding to it. Please create separate issues to discuss individual ideas/features.

[jkonecki]

http://dotnet.github.io/orleans/Ideas-for-Contributions

[sergeybykov]

Thanks! Of course, I forgot to put the link.

[mistakenot]

How about support for Rx style IObservables between grains? Seems like it would make a nice fit and possibly offer a richer feature set than observable grains as they are currently implemented.

On a side note, am looking forward to seeing where this project goes in general. Thanks for making it available.

[sergeybykov]

Do you mean something beyond IAsyncObservable/IAsyncObserver?

[gabikliot]

Can you give some code examples of what exactly do you mean by "Rx style IObservables between grains" in addition to what we already have here:
https://github.com/dotnet/orleans/tree/master/src/Orleans/Streams/Core
https://github.com/dotnet/orleans/blob/master/src/TestGrains/SampleStreamingGrain.cs

[jkonecki]

I could start by moving samples from code plex and look at the pluggable storage system next. I could create DocumentDB and RavenDB providers as well and see how the event sourced state providers would fit into the story in some consistent way.

Also, could you please update the wiki page with some general instructions on how the work should be carried out? For example, should we create a feature branch? Do you expect a PR once the whole work is done or at the beginning so you can follow the progress?

[jason-bragg]

I've been tinkering with using Doxygen to generate a reference manual. I'm of the opinion that an auto-generated reference manual would be a good way to keep detailed documentation up to date with the code with minimal effort. I was hoping to get a sense of the communities interest in such an effort prior to spending more time on it.

[jkonecki]

+1 for automated tool.

-1 for Doxygen website not working properly in Mobile Firefox. Hopefully generated documentation is better....

[sergeybykov]

We are still learning the process, so you all might need to educate us a bit. A feature branch seems like a natural way to go to me. What's the alternative? I guess a PR in the beginning would make sense for medium and large size features. But ultimately it should probably be up to the person writing the code - when they want to share and get feedback from others. Maybe we should try a few things and formulate the instructions later? If you can point to a good example of such instructions, that would help.

For RavenDB, are you planning to use https://github.com/OrleansContrib/orleans.storageprovider.ravendb from danielmarbach?

It's a good question how event sourced state providers fit the model. If they don't, maybe we should consider changing or expanding the model? Same question about support for on-demand loaded state properties. We are very open to ideas and suggestions how to improve it.

[jkonecki]

I would prefer to work on a feature branch and make a PR asap for any feedback. Let's see how it goes 😉

Yes, we have a bunch of storage providers in OrleansContrib which we could port to main repo.

ES providers will probably require a new interface since the reading / writing semantics are a bit different - but it should fit in nicely.

I don't know what are the requirements for loaded on-demand properties - let me create a separate issue to discuss it...

[jason-bragg]

@jkonecki I wasn't aware of the Doxygen + Mobile Firefox issue. Tertiary search generated results from 2013, is this still an issue? Given that google is using doxygen for documentation on it's projects, I suspect that there are few major issues with the tech. Is there another auto-doc tool you're recommend? It's been a while since I've worked with it, but doxygen still seems like the de facto standard.

[jkonecki]

@jason-bragg I'm talking about their website, not the generated documentation 😄

There was a Sandcastle project http://sandcastle.codeplex.com/ but it's dead now...

Don't get me wrong - I fully support your idea of generated documentation. I'm sure the doxygen will be fine.

[jthelin]

There are some useful guidelines on how to contribute to .NET projects on GitHub here:
https://github.com/dotnet/corefx/wiki/Contributing
https://github.com/dotnet/corefx/wiki/API-Review-Process
https://github.com/dotnet/corefx/wiki/Breaking-Changes

The main coding standards and “style guide” used for Orleans code is the .NET Framework Design Guide:
https://github.com/dotnet/corefx/wiki/Framework-Design-Guidelines-Digest

Note in particular that going forward, a .NET Contribution License Agreement (CLA) will be required for any non-trivial contributions to this project.
https://github.com/dotnet/corefx/wiki/Contribution-License-Agreement-%28CLA%29
If you have not already completed a CLA for other .NET projects, then you might want to start the paperwork process soon so that you are ready when the CLA Bot gets turned on “Real Soon Now” (tm) ;)

[jdom]

I had good experience with Sandcastle for documenting APIs with an MSDN style.
My recommendation is that even if some features like adding ravenDB support might be nice, not all necessarily fit in the core repo. This might be appropriate to put into a sibling repo or something that the core can link to. To give visibility, but it should be independent. Also, from the deployment perspective, it probably requires its own nuget package that doesn't force the ravendb dependency on everyone.

[sergeybykov]

Added "Support for dependency injection [Medium]" to the list.

[jkonecki]

@jdom - yes, the providers that depend on third party libraries will be separate from core Orleans.

[jdom]

BTW, I recommend that instead of having a list in a wiki, that you create a separate GitHub issue for each item, so it can be discussed in isolation, and also be assigned or update the status.
Also, for simpler tasks, you can also consider applying the tag "up for grabs", as there are already some aggregation sites out there like this: http://up-for-grabs.net/ for people that want to jump into and collaborate on an OSS project without too much friction.

[mistakenot]

@gabikliot Hadn't come across those yet, looks good. Thanks.

[sergeybykov]

@jdom - yes, that's what I suggested at the top: "Please create separate issues to discuss individual ideas/features."

That's a great suggestion about "up for grabs"!

[yevhen]

Right now, I'm working on something that covers items 3, 9, 10 from this list https://github.com/dotnet/orleans/wiki/Ideas-for-Contributions and makes item 4 somewhat irrelevant. Thus, the solution is pretty unusual :)

I'll post an update once PoC is done (2-3 days).

[richorama]

I'll have a go at 1.

Number 5 is partially addressed by SiloMon, although I would be the first to admit that it's lacking features.

[sergeybykov]

Great! I created issues for 1, 3, 4, 9 and 10 to discuss the details.

[kspeakman]

One thing that I haven't seen described is how you write unit tests for a grain. How do you inject mocks for other referenced grains? Logically speaking, the testing point and natural junction between actors would be the messages they send/receive. However, since messages are not explicit concepts in Orleans, I assume it will be necessary to mock the grains (proxies) which are interacted with.

[sergeybykov]

Does this question fit into 10. Support for dependency injection? Or you think it goes beyond that?
#39

[gabikliot]

We have examples of unit test with grains here:
https://github.com/dotnet/orleans/tree/master/src/Tester

Although you could definitely mock some grains while testing others, you don't have to. You can test your full application or its parts in a real silo (or multiple silos) environment running all in one process on your machine.

[yevhen]

@gabikliot That's an example of integration testing, not a unit test. It's impossible to test grains in isolation with this approach.

@kspeakman Hi, Kasey! Nice to see you here (if that is the same Kasey Speakman from DDDD/CQRS mailing list). At the moment real unit testing (when you can test grain in isolation) is tough. The problems were already discussed here, here and there.

The gist is, that there are no real seams provided by the framework. Even with DI some things will still be impossible to unit test. Yes, with DI you can inject interface implementations of your own stuff (eg, IRepository, IExternalService) but will get into troubles very quickly if your grain is using timers or reminders, or making deactivation requests, and even just accessing and identity of itself.

I went to the great lengths with unit testing and abstracted all those pesky framework dependencies inside Orleans.Bus. Maybe, one day something similar will appear in Orleans.

[yevhen]

@kspeakman

Logically speaking, the testing point and natural junction between actors would be the messages they send/receive. However, since messages are not explicit concepts in Orleans, I assume it will be necessary to mock the grains (proxies) which are interacted with

I completely agree with you. Taking into account that actors are single-threaded turn-based - they could be unit tested as a regular .NET object. Same techniques apply. Scenario based testing such as Given(Previous State) ->When (Message In) -> Then(Message Out / New State). With Event Sourcing it will be incredibly simple (and reliable). You know, the usual GWT with Past Events -> Command -> New Events.

BTW, nothing is holding you from using message passing and do your own dispatch (using a higher-order functions). This is already supported by Orleans.

[richorama]

I have done some 'editorial' work, and moved things around slightly.

@gabikliot I have included a tree structure.

@jthelin thanks - I'll send a PR when I'm done with the initial edits.

Does anyone have any original artwork for the Orleans logo (hexagons) it would be nice to have a high res version, with the shadow applied to a transparent (as opposed to white) background...

[sergeybykov]

@richorama I'll check on the original artwork. We should have a vector version somewhere to produce a high-resolution image.

[gabikliot]

Richard, I love how it looks like! I say lets do the following, in order:

1. Move it into Orleans repo.
2. Make sure it mirrors the wiki pages exactly and that we did not loose any content.
3. Close the Wiki pages.
4. Start accepting PRs for any new changes to the structure and content.

[jesuspsalas]

Amazing work :D

From: Richard Astbury [mailto:notifications@github.com]
Sent: viernes, 06 de marzo de 2015 4:28
To: dotnet/orleans
Subject: Re: [orleans] Ideas for contributions (#29)

There's no styling, and there's probably loads of broken links, but I've had a go at porting the wiki to github pages.

repo is here: http://richorama.github.io/orleans-docs/

web page is here: http://richorama.github.io/orleans-docs/

Does anyone have any creative talent (or know of a good template)?

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/29#issuecomment-77551759.

[richorama]

@gabikliot #212 is ready to merge :¬)

[gabikliot]

Merged! Thank you @richorama !

[gabikliot]

I deleted all wiki pages and all documentation is now located on http://dotnet.github.io/orleans/.

[sergeybykov]

@richorama I found and added the original icons - https://github.com/dotnet/orleans/tree/gh-pages/Icons. There are also .ai files if we need them.

[lnaie]

Hi,

They got my attention while getting to learn Orleans.

1. The skeleton of an azure worker role has changed into an async implementation:
   private async Task RunAsync(CancellationToken cancellationToken) { }
   It will be great to have AzureSilo.Run() supporting a cancellation token as well.

2. The initialization steps would be great to evolve towards a fluent api, for both the server and the client.
   For instance, this would be great:
   var config = new ClusterConfiguration().StandardLoad().SetupMyStorageProviders();

Thanks

[sergeybykov]

@lnaie Are you interested in submitting a PR for this? That would be great.

[colombod]

Is the migration to CoreFx started? I would love to participate

[sergeybykov]

@colombod As far as I know, it hasn't started in earnest. We only looked at the scope of the work with the compatibility tool, and assessed that it's pretty modest. Interested in starting the work? Quite a few people would appreciate progress in that direction.

[colombod]

That would be my pleasure!

[gabikliot]

Hi @colombod. Any progress on this front would be highly appreciated!
We run the compatibility tool some time ago. There are a couple of unsupported APIs, mainly about files (need to use streams instead) and code gen. We don't think it would be too hard to do the port. Perhaps a good way to start is to re-evaluate what needs to be ported exactly and then do the port in small steps, one API at a time (as opposite to one huge PR). That would make it much easier to validate and accept it, and also other will be able to join in and help.

[colombod]

Great, I also have to catch up with cored state and will do exactly what you propose. Reassing the state and plan. Do you think that also the roslyn migration would impact this porting?

[gabikliot]

I think Roslyn is related to the part when we decide how to do the code gen so it can work in core clr. I am still not sure how much of the code gen APIs are different in corefx vs. full clr. Maybe it will be a small porting effort and we won't need to redo it all. Or maybe it is much more pervasive and perhaps using Roslyn for code gen will simplify the whole story. We already have an open issue #40 about Roslyn, which is very related.

[colombod]

Did fork, is there an issue number for this item? Do you use GitFlow branching in the repo?

[gabikliot]

Opened an issue here: #368

[colombod]

Great, so just branching, not Gitflow. right?

[gabikliot]

Yes, we don't use Gitflow. Just branching.

[lnaie]

@sergeybykov Yes, I could give it a try.

[sergeybykov]

@lnaie Excellent! Let us know how we can help.