Bug or Feature? Are Tags 0.6.2 -> 1.0.6 releases? Document on NPM that there's a new package name.
nkuehn opened this issue · comments
Describe the bug
I am very interested in the AST on GraphQL merged as version 1.0.5.
But I (thought I) cannot use 1.0.5 in my project without using a hardwired Git commit.
- NPM (if I follow the documentation) gives me 0.6.3 as the latest version: https://www.npmjs.com/package/gatsby-mdx
- the package.json in master is at 0.6.2 : https://github.com/ChristopherBiscardi/gatsby-mdx/blob/master/packages/gatsby-mdx/package.json#L3
- the "latest release" on GitHub is 0.6.1 : https://github.com/ChristopherBiscardi/gatsby-mdx/releases. "More tags" shows that you are very active though with great features.
It took me a lot of trial / error / digging commits to find out that there is a new "1.0" branch that is the actual current plugin worked on but it's not configured as the default branch in git(Hub) https://github.com/ChristopherBiscardi/gatsby-mdx/tree/1.0/packages/gatsby-mdx and the docs don't show it.
Here the plugin is called gatsby-plugin-mdx
(better name :-)). But the documentation site still advises to install gatsby-mdx
, effectively locking you into an dead end if you don't spend the time I just spent to understand the situation.
To Reproduce
- Read the documentation and install.
- Read the Releases ( https://github.com/ChristopherBiscardi/gatsby-mdx/releases ) and what they contain. ´
- Find out that a new release or tag solves your problem
- Try to add that version to your package.json and run
yarn
. fail. Check NPM. No info but some confusion about 0.6.1 vs. 0.6.2 vs. 0.6.3.
Expected behavior
- Read the documentation and follow it.
- Be on a future proof path that makes you a happy user not causing support effort like this.
-> install the current package name andyarn upgrade
does the rest
Bonus 1: Hit GitHub and be on the actual main development branch.
Bonus: if google sends you to https://www.npmjs.com/package/gatsby-mdx , at least have some way to see that you should better use https://www.npmjs.com/package/gatsby-plugin-mdx . A link in the README, whatever. No need to deprecate that alltogether, but at least tell in some way.
You caught us while we were in transition moving to gatsby-plugin-mdx
. I just got it merged into the Gatsby repo last week and it is published from there now: gatsbyjs/gatsby#14657
The gatsby-mdx netlify site will be updated to redirect people to the Gatsby docs for MDX
great! That was really bad timing, don't take it personally and thanks for the effort!