[gatsby-source-contentful] create children nodes after parent was created

[pieh]

This fixes #4401, but issue a bit more nuanced than this fix alone:

Deleting possibly stale descendant nodes in createNode now force to create children nodes after creating parent node (or else children might be deleted upon parent node creation). This is fine (as there is no other way to remove stale nodes), but I don't think it's documented anywhere yet.

But before documenting that we should probably define when to use node parent/children because as of right now plugins do use them in at least 2 different ways:

• most importantly transformer plugins use them and it's quite important to use it there
• some source plugins use that relationship as extra link between nodes (that's in addition to fieldname___NODE relationship): gatsby-source-contentful (this is what caused Build Fails When Editing Existing Contentful Entries - 'TypeError: Cannot read property 'internal' of undefined' #4401), gatsby-source-wordpress and probably more

Is it fine to use parent/children in both ways?
If so I will try to add some warnings about situation like this (creating parent after the children) so plugin maintainers will have (more) helpful warning/error messages instead of non-descriptive error in gatsby internals. If parent/children should be reserved for transformers then parent/children should be more precisely documented and plugins updated to not use those fields in that cases.

I searched docs and currently found very few mentions of parent/children:

• https://www.gatsbyjs.org/docs/bound-action-creators/#createParentChildLink

This is used when you transform content from a node creating a new child node

• https://www.gatsbyjs.org/docs/bound-action-creators/#createNode
  description of params, but it's more technical,
• https://www.gatsbyjs.org/docs/node-interface/#transformer-plugins

Nodes created by transformer plugins are set as “children” of their “parent” nodes.

[gatsbybot]

Deploy preview for gatsbygram ready!

Built with commit 9ff09b1

https://deploy-preview-4429--gatsbygram.netlify.com

[gatsbybot]

Deploy preview for using-drupal ready!

Built with commit 6c5d52540ee3b3c2175f7068a96ab2acf22cc313

https://deploy-preview-4429--using-drupal.netlify.com

[pieh]

I will check failed test tomorrow, but from quick glance it's just snapshot not updated (order of nodes is changed)

[KyleAMathews]

Yeah, we've been doing this inconsistently. There's some source plugins that don't create the parent/child link and it's fine.

I can't think of any reason not to restrict parent/child relationships to source/transformed node relationships. Clearly defining that would simplify understanding I think how Gatsby constructs data relationships and how you should model your data in Gatsby if you're doing something custom.

parent/child is for transformers

Want to create links between nodes? Creating mappings or use ___NODE w/ createNodeField in onCreateNode.

[pieh]

Updated PR with quick fix for contentful. Will be doing pass through plugins to find other places where parent/children is used in addition to node linking in follow up PR.

This might potentially break some websites if they use childrenX instead of linked-nodes fields, but I think this need to be done.

I will also update parent/children docs. Is it sensible that setting parent should be most often (if not always) done in onCreateNode hook?

[KyleAMathews]

Yeah, in onCreateNode with https://www.gatsbyjs.org/docs/bound-action-creators/#createParentChildLink since you can't mutate other plugin's nodes.

Doing this for v2 would be great as most plugins are going to have breaking changes anyways and people will be expecting to do a lot of little upgrades. It'd be a pretty simple upgrade for most plugins as you'd just find/replace in your GraphQL queries.

[KyleAMathews]

Oh but yeah, don't make the breaking change here for gatsby-source-contentful. Do that on the v2 branch since I think we already incremented its major version there.

[pieh]

OK, I reverted PR to previous fix for master (keep parent/children, just delay creating children nodes to after parent node was created) - it wasn't potentially breaking change. I will create separate PR for v2 when I'll finish with similar fixes for other plugins in master.

[KyleAMathews]

Great, thanks!