Further readme improvements #21

goshacmd · 2017-02-01T15:49:15Z

sections specifically tailored to users of other side-effect management libraries
assure it's ok to use redux-cycles and something else side-by-side
simple stream/sink/source/epic definitions to the cycle.js section
table of contents
hacked together a quick logo

One thing I think we should settle on is what we call each individual program: a cycle, an epic, or something else.

Cycle kinda sounds nice, and is part of our new name but... I worry it might be easily conflated with Cycle.js the library
Epic is a word familiar to redux-observable users

lmatteis · 2017-02-01T16:19:45Z

README.md

+* [Drivers](#drivers)
+* [Utils](#utils)
+  * [`combineCycles`](#combinecycles)
+* [Testing](#testig)


#testing here instead of #testig

Fixed, thanks

goshacmd · 2017-02-01T16:22:10Z

README.md

+  <dd>is a stream of real-world events as they happen</dd>
+  <dt><strong>sink</strong></dt>
+  <dd>is a stream of commands to be performed</dd>
+  <dt><strong>cycle/epic</strong></dt>


lmatteis · 2017-02-01T16:23:38Z

README.md

 Redux-cycles provides an `ACTION` source, which is a stream of Redux actions, and listens to the `ACTION` sink.

+```


add ```js here for syntax highlighting

lmatteis · 2017-02-01T16:24:26Z

README.md

+  <dd>is a stream of real-world events as they happen</dd>
+  <dt><strong>sink</strong></dt>
+  <dd>is a stream of commands to be performed</dd>
+  <dt><strong>cycle/epic</strong></dt>


since this section is about Cycle.js perhaps we shouldn't have "epic" here as it's confusing (doesn't take sources/return sinks).

lmatteis · 2017-02-01T16:27:40Z

README.md

+The domain API layer often is not the easiest one to switch, so if you're thinking that... think of something smaller :)
+
+**Redux-saga** can still be valuable, even if using Redux-cycles.
+Certain sagas read crystall clear, sagas that orchestrate user flow.


Typo "crystal" rather than "crystall"

Also "read crystal clear;" use ; rather than ,

lmatteis · 2017-02-01T16:31:11Z

I guess we can call them "cycles" (since we have combineCycles). The difference with other Cycle.js functions is that our "cycles" MUST accept ACTION/STATE sources and MUST return an ACTION sink of standard flux actions (perhaps we need to add this somewhere in the docs).

EDIT: good point that it might be confusing with Cycle.js - not sure.

lmatteis · 2017-02-01T16:37:11Z

README.md

+
+* Move business logic out of action creators, leaving them pure and simple.
+
+You don't necessarily need Redux-cycle if your goal is only that.


Redux-cycles (missing 's')

lmatteis · 2017-02-01T16:38:08Z

README.md

+* Handle your side-effects declaratively.
+
+  Side-effect handling in Redux-saga makes testing easier compared to thunks, but you're still ultimately doing glorified function calls.
+  The Cycle.js architecture pushes side-effect handling further to the edges of your application, leaving your "cycles" (or "epcis") operate on pure streams.


We can remove (or "epics") here i think

lmatteis · 2017-02-01T16:38:34Z

README.md

+
+* Type your business logic.
+
+  Most of your business logic lives in sagas... and they are hard to impossible to statically type.


"... they are hard OR impossible"

goshacmd · 2017-02-01T16:38:53Z

@lmatteis I don't think every cycle must make use of and/or return ACTION. Some cycles like analytics, will be only action-in only. Others might be action-out only. And with custom drivers, it's also possible to have cycles that don't operate on ACTION at all

lmatteis · 2017-02-01T16:42:43Z

@goshakkk true. in fact combineCycles is generic enough to be used outside this project. I'm not sure about giving them a name then. Perhaps cycles is enough. We don't have to have a name like 'epics'. They're just functions that take sources and output sinks - Cycle.js should decide on what to call them

goshacmd · 2017-02-01T16:45:49Z

@lmatteis thing is, they are called "components" in Cycle.js but to me it looks like an artifact of it trying to take over the DOM, which I'd imagine will be both confusing to React developers, and in a way far from reality.

Cycle for pure side effect management needs another word... so the question is, what's it gonna be. I still fear "a cycle" / "cycles" is going to be inevitable confused for the library itself...

lmatteis · 2017-02-01T16:53:32Z

I don't see what's wrong with "cycles". We need the connection with Cycle.js - they're Cycle.js functions after all. How are they different from normal Cycle.js functions? In fact, you should be able to totally reuse your cycles in other programs that don't use redux-cycles.

nickbalestra · 2017-02-01T17:41:29Z

cycle.js provide a cyclic architecture, therefore the name. Cycles make total sense to me. They are nothing more then cycle.js app, mainly just functions. If we don't want to call them cycles as we fear it might create confusion with cycle.js (not sure about it) here few options:

functions & combineFunctions
mains & combineMains (cycle convention, not sure I like it in this case)
not sure about epics, as we want to avoid confusion I'll also try to avoid confusion with redux-observables.

I still think that cycles are pretty appropriate...

goshacmd · 2017-02-01T17:59:03Z

Ok, I guess we can go ahead with cycles for now, and resolve it later if it ends up being confusing.

nickbalestra · 2017-02-01T18:02:08Z

README.md

@@ -1,8 +1,31 @@
 # Redux-cycles
+
+<div align="center">
+  <img src="logo.png" alt="Cycle.js + Redux = <3" />


I think will more appropriate to have redux + cycle = love (in the same order as the name 'redux-cycles') as it is cycle in redux not vice-versa I would argue. Otherwise love this :) What if we simply pull logo from both project to make this (just an idea) ?

I've thought about that... but the Cycle logo isn't symmetric, its right side looks cut out, so I thought the logo would look better if the plus sign kind of filled that cut; having it in the middle would probably look odd-ish.

What do you mean by pulling both of the logos? I already made a picture by combining these. If you mean we should have two image tags and plus, equals, and a heart as text, I'd say formatting that will be terrible on its own. The people wouldn't also be able to easily save the logo to use it elsewhere (like in a tweet)

The alternative version would be:

and the one in this PR for reference:

Maybe even simplify a bit and use a blue heart to be more in line, color wise, with Redux and Cycle logos:

@nickbalestra @lmatteis thoughts?

I would go with the first (redux on the left) to favour meaning over aesthetics. Yes, Good point on formatting and having a picture instead!

I kinda like the red heart.
Both forms are nice,
I read the first as redux plus cycle = love while the second redux loves cycle both make sense so I'm fine with either :)

👍 for the redux + cyclejs

nickbalestra · 2017-02-01T18:06:27Z

What is your point on how we use 'main' for example (...use createCycleMiddleware() which takes as first argument your main Cycle.js...) Is this clear? Should we instead use root as it is more common redux word?

lmatteis · 2017-02-01T20:38:41Z

I'm also thinking that we can define a "cycle" as a function that takes at least 2 sources (ACTION & STATE) and it MAY return to a writable ACTION sink. This is what sets cycles apart from normal Cycle.js functions imo.

Regarding the wording for "main", I'm not sure because main is what is used in the Cyclejs community. Perhaps it's a rootCycle given the definition above?

nickbalestra · 2017-02-02T09:26:45Z

Yup I like the cycle defition you provided! And yes now that I think about main, it make sense (not just cause it's beein used in the cycle.js community)

goshacmd · 2017-02-02T09:40:26Z

Updated the cycle definition in the PR, and swapped the logo. Good to merge?

nickbalestra · 2017-02-02T09:44:21Z

@goshakkk As I added the drivers parameter to be optional you may want to rebase and make sure that part still there. After that is good to go for me

nickbalestra

💯 💅 ❤️

goshacmd force-pushed the more-readme-improvs branch from 3fd7232 to 285b2c8 Compare February 1, 2017 15:49

lmatteis reviewed Feb 1, 2017

View reviewed changes

goshacmd force-pushed the more-readme-improvs branch from 285b2c8 to 881b94f Compare February 1, 2017 16:22

goshacmd commented Feb 1, 2017

View reviewed changes

lmatteis reviewed Feb 1, 2017

View reviewed changes

goshacmd force-pushed the more-readme-improvs branch from 881b94f to 29abc19 Compare February 1, 2017 16:27

lmatteis reviewed Feb 1, 2017

View reviewed changes

goshacmd force-pushed the more-readme-improvs branch 2 times, most recently from 1f97dee to dd4dc6c Compare February 1, 2017 16:41

nickbalestra reviewed Feb 1, 2017

View reviewed changes

goshacmd force-pushed the more-readme-improvs branch from dd4dc6c to 4cdd286 Compare February 2, 2017 09:15

goshacmd added 2 commits February 2, 2017 12:49

Add I-already-know-X to readme, add TOC

c3fdc98

Add a logo

c63f378

goshacmd force-pushed the more-readme-improvs branch from 4cdd286 to c63f378 Compare February 2, 2017 09:49

nickbalestra approved these changes Feb 2, 2017

View reviewed changes

lmatteis approved these changes Feb 2, 2017

View reviewed changes

goshacmd merged commit 4a0a18d into master Feb 2, 2017

goshacmd deleted the more-readme-improvs branch February 2, 2017 10:04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Further readme improvements #21

Further readme improvements #21

goshacmd commented Feb 1, 2017

lmatteis Feb 1, 2017

goshacmd Feb 1, 2017

goshacmd Feb 1, 2017

lmatteis Feb 1, 2017

lmatteis Feb 1, 2017 •

edited

Loading

lmatteis Feb 1, 2017 •

edited

Loading

lmatteis Feb 1, 2017

lmatteis commented Feb 1, 2017 •

edited

Loading

lmatteis Feb 1, 2017

lmatteis Feb 1, 2017

lmatteis Feb 1, 2017

goshacmd commented Feb 1, 2017

lmatteis commented Feb 1, 2017

goshacmd commented Feb 1, 2017

lmatteis commented Feb 1, 2017

nickbalestra commented Feb 1, 2017 •

edited

Loading

goshacmd commented Feb 1, 2017

nickbalestra Feb 1, 2017

goshacmd Feb 1, 2017

goshacmd Feb 1, 2017

goshacmd Feb 1, 2017

goshacmd Feb 1, 2017

nickbalestra Feb 1, 2017

nickbalestra Feb 1, 2017

lmatteis Feb 1, 2017

nickbalestra commented Feb 1, 2017

lmatteis commented Feb 1, 2017 •

edited

Loading

nickbalestra commented Feb 2, 2017

goshacmd commented Feb 2, 2017

nickbalestra commented Feb 2, 2017 •

edited

Loading

nickbalestra left a comment

		Redux-cycles provides an `ACTION` source, which is a stream of Redux actions, and listens to the `ACTION` sink.

		```


		* Move business logic out of action creators, leaving them pure and simple.

		You don't necessarily need Redux-cycle if your goal is only that.


		* Type your business logic.

		Most of your business logic lives in sagas... and they are hard to impossible to statically type.

Further readme improvements #21

Further readme improvements #21

Conversation

goshacmd commented Feb 1, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lmatteis Feb 1, 2017 • edited Loading

Choose a reason for hiding this comment

lmatteis Feb 1, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lmatteis commented Feb 1, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

goshacmd commented Feb 1, 2017

lmatteis commented Feb 1, 2017

goshacmd commented Feb 1, 2017

lmatteis commented Feb 1, 2017

nickbalestra commented Feb 1, 2017 • edited Loading

goshacmd commented Feb 1, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nickbalestra commented Feb 1, 2017

lmatteis commented Feb 1, 2017 • edited Loading

nickbalestra commented Feb 2, 2017

goshacmd commented Feb 2, 2017

nickbalestra commented Feb 2, 2017 • edited Loading

nickbalestra left a comment

Choose a reason for hiding this comment

lmatteis Feb 1, 2017 •

edited

Loading

lmatteis Feb 1, 2017 •

edited

Loading

lmatteis commented Feb 1, 2017 •

edited

Loading

nickbalestra commented Feb 1, 2017 •

edited

Loading

lmatteis commented Feb 1, 2017 •

edited

Loading

nickbalestra commented Feb 2, 2017 •

edited

Loading