search

orchidhq / Orchid

Build and deploy beautiful documentation sites that grow with you
https://orchid.run
GNU General Public License v3.0
514 stars 53 forks source link

gh-pages deploy no loger working #284

Closed DanySK closed 5 years ago

DanySK commented 5 years ago

I am trying version 0.17.1, but deploy fails:

Deploy Starting...

[WARN] Warnings:
[WARN] ModularList: 
[WARN]     - OrchidPublisher type [ghPages] could not be found

Any clue on the reason?

DanySK commented 5 years ago

Issue remains with version 0.17.0, works with 0.16.10 instead

cjbrooks12 commented 5 years ago

Yeah, ghPages has been renamed to githubPages for consistency and also requires the new OrchidGithub dependency to be added. It's all documented in the release notes, be sure to read the full 0.16.x to 0.17.x migration guide for any other breaking changes.

Orchid uses semantic versioning and while it's still using 0.x.x versions you can expect minor version bumps to contain breaking changes, so be sure to read the release notes carefully. In most cases, these are internal APIs, but they may also be minor end-user breakages which improve the overall consistency and user experience.

I apologize for the confusion here; I try to be very clear in the release notes and in social media posts when there are breaking changes to avoid this. I will try to make these kinds of things more obvious, and should probably start making a standardized process of deprecation for features that will be removed or renamed, before I actually do.

DanySK commented 5 years ago

I'm giving the instructions a try immediately. I didn't know there was a migration guide.

cjbrooks12 commented 5 years ago

No worries. The migration guide isn't really an official thing now, it's just part of the release notes for that version. I'm trying to find a better way to manage and publicize all this stuff, I'm definitely open to suggestions if you have any!

DanySK commented 5 years ago

A very lightweight deprecation process is providing textual feedback before feature removal, e.g. 0.16.x supports the old ghPages; 0.17.x still does so, but prints a clear warning, including instructions on how to upgrade (possibly a link to the migration guide), and quits complaining once the new structure is in place; 0.18.0 drops support.

This makes it easier to upgrade even when documentation is a bit sparse, because by doing it step-by-step the user gets guided.

Anyway, I applied the migration guide suggestions and everything is working as expected again.

Thanks!