I'm spinning up some docs for holonix, feedback welcome :)

Technical Discussion Holonix
#21

@thedavidmeister: Is this info in the readme or docs dir? I failed to find it with a quick scan of both, but then located it here after some searching.

#22

Yes, auto tags would be helpful. I am not sure if auto tag has been implemented in the feature roadmap. I’ll look into it.

https://meta.discourse.org/t/a-roadmap-for-tags/85459 @marcus

#23

@jmday well it’s in a WIP branch… there will be instructions by the time i finish the branch :slight_smile:

#24

ok, please review/feedback on first pass of the holonix docs

especially if there is critical information missing, so i can update it

@jmday @zippy @dhtnetwork @marcus @pythagorean @pospi @pjkundert @philipbeadle @freesig

ignore the theme, @dhtnetwork is sorting me out with something on brand

#25

I would recommend merging the three-p’s into a single “approach”, “theory”, or “assumptions” section. They all seem like logically part of the same thing which is explaining the why and how of Holonix. Having them take up the top three items of menu real-estate seems like a bit too much.

4 Likes
#26

@zippy aight, i got some other feedback coming in through other channels, i’ll give it a few days to aggregate then i’ll do another sweep

makes sense i’ll combine those three into a single page

#27

@thedavidmeister - Install Holonix seems like there is some duplicate/similar info with the Quick Start page. Will it confuse people?

https://docs.holochain.love/docs/install/

How is this different/similar to the Quick Start page?

Brand - logos/colors yes will get those to you.

#28

@thedavidmeister thankyou so much for this… really helpful work. I’ve updated our setup to use the more idiomatic setup and it was pretty painless to deal with.

Our scripts are still kept as NPM commands which must be run inside nix-shell, though. Would you recommend cutting these over to Nix, or would that just slow things down by requiring the Nix shell to boot up for each command? Is there a way to run Nix scripts from within Nix without reloading the environment in a sub-shell? If so, I didn’t see those particulars documented.

The other thing potentially missing is configuration instructions for more advanced scripts- in particular, if we do switch wholly to Nix then I want to be able to fork subprocesses and run multiple commands in parallel easily.

1 Like
What is the *worst* of holonix onboarding? 2019-Q3
#29

The other one that’s missing is a description of the available Nix commands provided by Holonix and what they do (eg. hn-flush). Or better yet, to avoid the maintenance burden this could just be instructions of where to look in the Holonix codebase to find them, and how to interpret them.

Additionally if there is a command to sync all Cargo.toml files with the version of holochain-rust configured in Holonix, that would remove a lot of hassle from the upgrade process.

#30

Oh one final request- instructions on setting up CI on Travis would be amazing 'cos it’s free and integrated into Github so a no brained for OSS projects.

If you can’t invoke Nix commands without skipping the sub-shelling then I am guessing a recommendation would be that two versions of test commands be provided- one to execute directly (for use within nix-shell during development), and one to be executed by CI (which would need to boot up a subshell… unless there are NixOS CI servers?)

1 Like
#31

Only got through configure… gotta get to other things, but please review and let me know if it’s helpful?

Holonix doc feedback/suggestions

This is an awesome start, @thedavidmeister.

The following may be appropriate for someone other than you to make another pass through…

Some Suggestions

  • add document title, e.g. “holonix for Holochain”
  • add “Overview” section with clearly & succinctly stated bottom line of why we have and use nix, how holonix fits in to the Holochain picture, and where else nix fits into the Holo picture so people can quickly resolve any confusions.
  • move Productive/Portable/Predictable as either sub-sections of the shorter “Overview” section or later in the docs (after install and configure?)
  • Install holonix section:
    • Allow user to pick Mac/Linux/Windows and only show them what they need to know. e.g. selectable tab at top of page that hides content for non-selected OSes or just use different pages.
    • I sense many people will just want to install and use for hApp development. Can we move anything they don’t absolutely need to know to other “advanced” sections?
    • Regarding: The Mac prereq: “You may need to install the command line tools.” Is it possible for someone to find out so we can make a clear requirement/recommendation here?
    • In the “Windows” sub-section, we give LOTS of options and explanations. Can we choose a single recommended method for the majority of users? I realize there will be diverse needs, but let’s default to something appropriate and maybe provide another sub-section on advanced windows holonix issues?
  • Configure section:
    • Reduce options to a single recommended approach and then provide another (maybe sub-)section for advanced config approaches.
    • The computer hostname in the example shell sessions being “nixos” may invite some confusion. I suggest altering the examples to use a hostname that wouldn’t potentially conflict with the learning concepts being conveyed.
    • Use static text instead of vids?.. Vids of a terminal session only make sense to me if we’re showing some characters getting overwritten or if there are timing issues being discussed. Maybe default to showing the completed session and let people “play” if they want to? I found it annoying waiting til it appeared to read the next line.
#32

this is all awesome everyone!

especially @jmday and @pospi for the deep dives

keep it coming

i’m going to let this thread simmer for a bit, give everyone the opportunity to stew in what is there and see how it relates to their own work

i’m thinking that i merge in what is there now and put a followup PR that works through this thread in 1-2 weeks ish

1 Like
#33

The docs were helpful in empowering me to control hc and holochain versions and delving deeper into nix-shell options, but the 3-p’s did throw me off.

Of @zippy’s category suggestions, “Approach” resonates most with me however as an outside developer, and someone discovering holochain and another tool I’m supposed to now learn called “Holonix”. --> The next question in my mind is “Why do I have to learn Holonix?”

"Why Holonix?"

  • Productive
  • Portable
  • Predictable
#34

I like this as a unification for the 3ps!

#35

1 more request (can’t remember if I already said, sorry) - documentation on how to spin up Travis (it’s free for OSS projects on Github) or other CI server to run tests within a Nix environment would be really great :slight_smile:

#36

sure, FYI cicle ci (also free for FOSS) is basically this:

version: 2

jobs:
 build:
  docker:
   - image: holochain/holonix:latest
  steps:
   - checkout
   - run: nix-shell --run {{ your test command here }}

travis would be very similar, just use the holochain/holonix:latest docker box as a starting point @pospi

1 Like
#38

@pospi for npm commands you need to make the local binaries show up on your $PATH

node normally does this through symlinks but this isn’t friendly to nix (read only store) nor VMs on windows (breaks vagrant)

this workaround is fine for me https://docs.holochain.love/docs/node/ and i’m pretty sure there are nicer ways to do it :slight_smile:

#39

this thread has pretty much run its course i think, i’m going to merge in what i have so far and put issues up in the issue queue for each outstanding suggestion, thanks to everyone for their contributions, let’s move over to github moving forward for this round of feedback :slight_smile:

#40

Hey, TravisCI configuration was pretty easy too- https://github.com/holo-rea/holo-rea/commit/bedbbea6a91a3969f51e5199eea7a2b4f588d689

Note that I had issues with CircleCI… a couple of tests failing for no reason. I think perhaps it has more constrained worker resources than Travis, but ¯\_(ツ)_/¯

The other issue is that Travis times out because builds take too long, but that’s logged elsewhere.

#41

yeah i had various issues hitting “hidden” resource limits in travis (more so than circle)

things like:

  • slower cache access, non deterministic cache, cache monotonically getting heavier over time
  • max log size allowed in the GUI before build is canceled
  • build times
  • not as good nix/docker support

if it’s working for you don’t change anything, but yeah, i haven’t found a “silver bullet” provider yet :sweat_smile: