github/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2024-11-14 20:37:55 -05:00
Code Issues Projects Releases Packages Wiki Activity

Revise the deprecation logging

Browse source 
This introduces a more automatic way of increasing the log levels for deprecation log statements based on the version it was deprecated.

The thresholds are a little arbitrary, but

* We log INFO for 6 releases
* We log WARN for another 6 releases
* THen ERROR (failing the build)

This should give theme authors plenty of time to catch up without having the log filled with warnings.
This commit is contained in:
Bjørn Erik Pedersen 2023-10-26 09:38:13 +02:00
parent c4a530f104
commit 71fd79a3f4
12 changed files with 93 additions and 68 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
commands/commandeer.go
View file

@ -38,6 +38,7 @@ import (
"github.com/gohugoio/hugo/common/hstrings"
"github.com/gohugoio/hugo/common/htime"
"github.com/gohugoio/hugo/common/hugo"
"github.com/gohugoio/hugo/common/loggers"
"github.com/gohugoio/hugo/common/paths"
"github.com/gohugoio/hugo/config"
@ -50,9 +51,7 @@ import (
"github.com/spf13/cobra"
)
var (
errHelp = errors.New("help requested")
)
var errHelp = errors.New("help requested")
// Execute executes a command.
func Execute(args []string) error {
@ -182,11 +181,9 @@ func (r *rootCommand) ConfigFromConfig(key int32, oldConf *commonConfig) (*commo
cfg: oldConf.cfg,
fs: fs,
}, nil
})
return cc, err
}
func (r *rootCommand) ConfigFromProvider(key int32, cfg config.Provider) (*commonConfig, error) {
@ -211,7 +208,7 @@ func (r *rootCommand) ConfigFromProvider(key int32, cfg config.Provider) (*commo
if !cfg.IsSet("workingDir") {
cfg.Set("workingDir", dir)
} else {
if err := os.MkdirAll(cfg.GetString("workingDir"), 0777); err != nil {
if err := os.MkdirAll(cfg.GetString("workingDir"), 0o777); err != nil {
return nil, fmt.Errorf("failed to create workingDir: %w", err)
}
}
@ -303,7 +300,6 @@ func (r *rootCommand) ConfigFromProvider(key int32, cfg config.Provider) (*commo
})
return cc, err
}
func (r *rootCommand) HugFromConfig(conf *commonConfig) (*hugolib.HugoSites, error) {
@ -348,7 +344,6 @@ func (r *rootCommand) Run(ctx context.Context, cd *simplecobra.Commandeer, args
err := b.build()
return err
}()
if err != nil {
return err
}
@ -434,12 +429,13 @@ func (r *rootCommand) createLogger(running bool) (loggers.Logger, error) {
}
} else {
if r.verbose {
helpers.Deprecated("--verbose", "use --logLevel info", false)
hugo.Deprecate("--verbose", "use --logLevel info", "v0.114.0")
hugo.Deprecate("--verbose", "use --logLevel info", "v0.114.0")
level = logg.LevelInfo
}
if r.debug {
helpers.Deprecated("--debug", "use --logLevel debug", false)
hugo.Deprecate("--debug", "use --logLevel debug", "v0.114.0")
level = logg.LevelDebug
}
}
@ -453,7 +449,6 @@ func (r *rootCommand) createLogger(running bool) (loggers.Logger, error) {
}
return loggers.New(optsLogger), nil
}
func (r *rootCommand) Reset() {
@ -519,7 +514,6 @@ func applyLocalFlagsBuildConfig(cmd *cobra.Command, r *rootCommand) {
_ = cmd.Flags().SetAnnotation("cacheDir", cobra.BashCompSubdirsInDir, []string{})
cmd.Flags().StringP("contentDir", "c", "", "filesystem path to content directory")
_ = cmd.Flags().SetAnnotation("theme", cobra.BashCompSubdirsInDir, []string{"themes"})
}
// Flags needed to do a build (used by hugo and hugo server commands)
@ -558,7 +552,6 @@ func applyLocalFlagsBuild(cmd *cobra.Command, r *rootCommand) {
cmd.Flags().StringSlice("disableKinds", []string{}, "disable different kind of pages (home, RSS etc.)")
cmd.Flags().Bool("minify", false, "minify any supported output format (HTML, XML etc.)")
_ = cmd.Flags().SetAnnotation("destination", cobra.BashCompSubdirsInDir, []string{})
}
func (r *rootCommand) timeTrack(start time.Time, name string) {

56
common/hugo/hugo.go
View file

@ -22,14 +22,15 @@ import (
"sort"
"strings"
"sync"
"time"
godartsassv1 "github.com/bep/godartsass"
"github.com/bep/logg"
"github.com/mitchellh/mapstructure"
"time"
"github.com/bep/godartsass/v2"
"github.com/gohugoio/hugo/common/hexec"
"github.com/gohugoio/hugo/common/loggers"
"github.com/gohugoio/hugo/hugofs/files"
"github.com/spf13/afero"
@ -183,8 +184,10 @@ type buildInfo struct {
*debug.BuildInfo
}
var bInfo *buildInfo
var bInfoInit sync.Once
var (
bInfo *buildInfo
bInfoInit sync.Once
)
func getBuildInfo() *buildInfo {
bInfoInit.Do(func() {
@ -211,7 +214,6 @@ func getBuildInfo() *buildInfo {
bInfo.GoArch = s.Value
}
}
})
return bInfo
@ -255,7 +257,7 @@ func GetDependencyListNonGo() []string {
}
if dartSass := dartSassVersion(); dartSass.ProtocolVersion != "" {
var dartSassPath = "github.com/sass/dart-sass-embedded"
dartSassPath := "github.com/sass/dart-sass-embedded"
if IsDartSassV2() {
dartSassPath = "github.com/sass/dart-sass"
}
@ -346,3 +348,45 @@ var (
func IsDartSassV2() bool {
return !strings.Contains(DartSassBinaryName, "embedded")
}
// Deprecate informs about a deprecation starting at the given version.
//
// A deprecation typically needs a simple change in the template, but doing so will make the template incompatible with older versions.
// Theme maintainers generally want
// 1. No warnings or errors in the console when building a Hugo site.
// 2. Their theme to work for at least the last few Hugo versions.
func Deprecate(item, alternative string, version string) {
level := deprecationLogLevelFromVersion(version)
DeprecateLevel(item, alternative, version, level)
}
// DeprecateLevel informs about a deprecation logging at the given level.
func DeprecateLevel(item, alternative, version string, level logg.Level) {
var msg string
if level == logg.LevelError {
msg = fmt.Sprintf("%s was deprecated in Hugo %s and will be removed in Hugo %s. %s", item, version, CurrentVersion.Next().ReleaseVersion(), alternative)
} else {
msg = fmt.Sprintf("%s was deprecated in Hugo %s and will be removed in a future release. %s", item, version, alternative)
}
loggers.Log().Logger().WithLevel(level).Logf(msg)
}
// We ususally do about one minor version a month.
// We want people to run at least the current and previous version without any warnings.
// We want people who don't update Hugo that often to see the warnings and errors before we remove the feature.
func deprecationLogLevelFromVersion(ver string) logg.Level {
from := MustParseVersion(ver)
to := CurrentVersion
minorDiff := to.Minor - from.Minor
switch {
case minorDiff >= 12:
// Start failing the build after about a year.
return logg.LevelError
case minorDiff >= 6:
// Start printing warnings after about six months.
return logg.LevelWarn
default:
return logg.LevelInfo
}
}

15
common/hugo/hugo_test.go
View file

@ -17,6 +17,7 @@ import (
"fmt"
"testing"
"github.com/bep/logg"
qt "github.com/frankban/quicktest"
)
@ -49,6 +50,20 @@ func TestHugoInfo(t *testing.T) {
c.Assert(devHugoInfo.IsServer(), qt.Equals, true)
}
func TestDeprecationLogLevelFromVersion(t *testing.T) {
c := qt.New(t)
c.Assert(deprecationLogLevelFromVersion("0.55.0"), qt.Equals, logg.LevelError)
ver := CurrentVersion
c.Assert(deprecationLogLevelFromVersion(ver.String()), qt.Equals, logg.LevelInfo)
ver.Minor -= 1
c.Assert(deprecationLogLevelFromVersion(ver.String()), qt.Equals, logg.LevelInfo)
ver.Minor -= 6
c.Assert(deprecationLogLevelFromVersion(ver.String()), qt.Equals, logg.LevelWarn)
ver.Minor -= 6
c.Assert(deprecationLogLevelFromVersion(ver.String()), qt.Equals, logg.LevelError)
}
type testConfig struct {
environment string
running bool

9
common/hugo/version.go
View file

@ -67,8 +67,11 @@ func (h VersionString) String() string {
// Compare implements the compare.Comparer interface.
func (h VersionString) Compare(other any) int {
v := MustParseVersion(h.String())
return compareVersions(v, other)
return compareVersions(h.Version(), other)
}
func (h VersionString) Version() Version {
return MustParseVersion(h.String())
}
// Eq implements the compare.Eqer interface.
@ -264,7 +267,6 @@ func compareFloatWithVersion(v1 float64, v2 Version) int {
if v1maj > v2.Major {
return 1
}
if v1maj < v2.Major {
@ -276,7 +278,6 @@ func compareFloatWithVersion(v1 float64, v2 Version) int {
}
return -1
}
func GoMinorVersion() int {

3
config/allconfig/allconfig.go
View file

@ -27,6 +27,7 @@ import (
"time"
"github.com/gohugoio/hugo/cache/filecache"
"github.com/gohugoio/hugo/common/hugo"
"github.com/gohugoio/hugo/common/loggers"
"github.com/gohugoio/hugo/common/maps"
"github.com/gohugoio/hugo/common/urls"
@ -784,7 +785,7 @@ func fromLoadConfigResult(fs afero.Fs, logger loggers.Logger, res config.LoadCon
// We accidentally allowed it in the past, so we need to support it a little longer,
// But log a warning.
if _, found := params[kk]; !found {
helpers.Deprecated(fmt.Sprintf("config: languages.%s.%s: custom params on the language top level", k, kk), fmt.Sprintf("Put the value below [languages.%s.params]. See https://gohugo.io/content-management/multilingual/#changes-in-hugo-01120", k), false)
hugo.Deprecate(fmt.Sprintf("config: languages.%s.%s: custom params on the language top level", k, kk), fmt.Sprintf("Put the value below [languages.%s.params]. See https://gohugo.io/content-management/multilingual/#changes-in-hugo-01120", k), "v0.112.0")
params[kk] = vv
}
}

16
helpers/general.go
View file

@ -27,9 +27,6 @@ import (
"unicode"
"unicode/utf8"
"github.com/gohugoio/hugo/common/hugo"
"github.com/gohugoio/hugo/common/loggers"
"github.com/spf13/afero"
"github.com/jdkato/prose/transform"
@ -246,19 +243,6 @@ func compareStringSlices(a, b []string) bool {
return true
}
// Deprecated informs about a deprecation, but only once for a given set of arguments' values.
// If the err flag is enabled, it logs as an ERROR (will exit with -1) and the text will
// point at the next Hugo release.
// The idea is two remove an item in two Hugo releases to give users and theme authors
// plenty of time to fix their templates.
func Deprecated(item, alternative string, err bool) {
if err {
loggers.Log().Errorf("%s is deprecated and will be removed in Hugo %s. %s", item, hugo.CurrentVersion.Next().ReleaseVersion(), alternative)
} else {
loggers.Log().Warnf("%s is deprecated and will be removed in a future release. %s", item, alternative)
}
}
// SliceToLower goes through the source slice and lowers all values.
func SliceToLower(s []string) []string {
if s == nil {

7
hugolib/hugo_sites_build.go
View file

@ -25,7 +25,6 @@ import (
"github.com/bep/logg"
"github.com/gohugoio/hugo/hugofs/files"
"github.com/gohugoio/hugo/langs"
"github.com/gohugoio/hugo/publisher"
"github.com/gohugoio/hugo/tpl"
@ -40,14 +39,8 @@ import (
"github.com/gohugoio/hugo/output"
"github.com/fsnotify/fsnotify"
"github.com/gohugoio/hugo/helpers"
)
func init() {
// To avoid circular dependencies, we set this here.
langs.DeprecationFunc = helpers.Deprecated
}
// Build builds all sites. If filesystem events are provided,
// this is considered to be a potential partial rebuild.
func (h *HugoSites) Build(config BuildCfg, events ...fsnotify.Event) error {

6
hugolib/page__meta.go
View file

@ -130,7 +130,7 @@ func (p *pageMeta) Aliases() []string {
}
func (p *pageMeta) Author() page.Author {
helpers.Deprecated(".Author", "Use taxonomies.", false)
hugo.Deprecate(".Author", "Use taxonomies.", "v0.98.0")
authors := p.Authors()
for _, author := range authors {
@ -140,7 +140,7 @@ func (p *pageMeta) Author() page.Author {
}
func (p *pageMeta) Authors() page.AuthorList {
helpers.Deprecated(".Authors", "Use taxonomies.", true)
hugo.Deprecate(".Author", "Use taxonomies.", "v0.112.0")
return nil
}
@ -226,7 +226,7 @@ func (p *pageMeta) Path() string {
{{ $path = .Path }}
{{ end }}
`
helpers.Deprecated(".Path when the page is backed by a file", "We plan to use Path for a canonical source path and you probably want to check the source is a file. To get the current behaviour, you can use a construct similar to the one below:\n"+example, false)
p.s.Log.Warnln(".Path when the page is backed by a file is deprecated. We plan to use Path for a canonical source path and you probably want to check the source is a file. To get the current behaviour, you can use a construct similar to the one below:\n" + example)
}

14
hugolib/site_new.go
View file

@ -31,7 +31,6 @@ import (
"github.com/gohugoio/hugo/config"
"github.com/gohugoio/hugo/config/allconfig"
"github.com/gohugoio/hugo/deps"
"github.com/gohugoio/hugo/helpers"
"github.com/gohugoio/hugo/identity"
"github.com/gohugoio/hugo/langs"
"github.com/gohugoio/hugo/langs/i18n"
@ -48,9 +47,7 @@ import (
"github.com/gohugoio/hugo/tpl/tplimpl"
)
var (
_ page.Site = (*Site)(nil)
)
var _ page.Site = (*Site)(nil)
type Site struct {
conf *allconfig.Config
@ -236,7 +233,6 @@ func NewHugoSites(cfg deps.DepsCfg) (*HugoSites, error) {
}
return h, err
}
func newHugoSitesNew(cfg deps.DepsCfg, d *deps.Deps, sites []*Site) (*HugoSites, error) {
@ -358,7 +354,7 @@ func newHugoSitesNew(cfg deps.DepsCfg, d *deps.Deps, sites []*Site) (*HugoSites,
// Returns true if we're running in a server.
// Deprecated: use hugo.IsServer instead
func (s *Site) IsServer() bool {
helpers.Deprecated(".Site.IsServer", "Use hugo.IsServer instead.", false)
hugo.Deprecate(".Site.IsServer", "Use hugo.IsServer instead.", "v0.120.0")
return s.conf.Internal.Running
}
@ -377,7 +373,7 @@ func (s *Site) Copyright() string {
}
func (s *Site) RSSLink() template.URL {
helpers.Deprecated("Site.RSSLink", "Use the Output Format's Permalink method instead, e.g. .OutputFormats.Get \"RSS\".Permalink", false)
hugo.Deprecate("Site.RSSLink", "Use the Output Format's Permalink method instead, e.g. .OutputFormats.Get \"RSS\".Permalink", "v0.114.0")
rssOutputFormat := s.home.OutputFormats().Get("rss")
return template.URL(rssOutputFormat.Permalink())
}
@ -449,13 +445,13 @@ func (s *Site) Social() map[string]string {
// Deprecated: Use .Site.Config.Services.Disqus.Shortname instead
func (s *Site) DisqusShortname() string {
helpers.Deprecated(".Site.DisqusShortname", "Use .Site.Config.Services.Disqus.Shortname instead.", false)
hugo.Deprecate(".Site.DisqusShortname", "Use .Site.Config.Services.Disqus.Shortname instead.", "v0.120.0")
return s.Config().Services.Disqus.Shortname
}
// Deprecated: Use .Site.Config.Services.GoogleAnalytics.ID instead
func (s *Site) GoogleAnalytics() string {
helpers.Deprecated(".Site.GoogleAnalytics", "Use .Site.Config.Services.GoogleAnalytics.ID instead.", false)
hugo.Deprecate(".Site.GoogleAnalytics", "Use .Site.Config.Services.GoogleAnalytics.ID instead.", "v0.120.0")
return s.Config().Services.GoogleAnalytics.ID
}

5
source/fileInfo.go
View file

@ -21,6 +21,7 @@ import (
"time"
"github.com/bep/gitmap"
"github.com/gohugoio/hugo/common/hugo"
"github.com/gohugoio/hugo/common/paths"
"github.com/gohugoio/hugo/hugofs/files"
@ -63,7 +64,6 @@ type fileOverlap interface {
}
type FileWithoutOverlap interface {
// Filename gets the full path and filename to the file.
Filename() string
@ -102,7 +102,6 @@ type FileWithoutOverlap interface {
// FileInfo describes a source file.
type FileInfo struct {
// Absolute filename to the file on disk.
filename string
@ -143,7 +142,7 @@ func (fi *FileInfo) Dir() string { return fi.relDir }
// Extension is an alias to Ext().
func (fi *FileInfo) Extension() string {
helpers.Deprecated(".File.Extension", "Use .File.Ext instead. ", false)
hugo.Deprecate(".File.Extension", "Use .File.Ext instead.", "v0.96.0")
return fi.Ext()
}

4
tpl/collections/collections.go
View file

@ -28,10 +28,10 @@ import (
"errors"
"github.com/gohugoio/hugo/common/collections"
"github.com/gohugoio/hugo/common/hugo"
"github.com/gohugoio/hugo/common/maps"
"github.com/gohugoio/hugo/common/types"
"github.com/gohugoio/hugo/deps"
"github.com/gohugoio/hugo/helpers"
"github.com/gohugoio/hugo/langs"
"github.com/gohugoio/hugo/tpl/compare"
"github.com/spf13/cast"
@ -200,7 +200,7 @@ func (ns *Namespace) Dictionary(values ...any) (map[string]any, error) {
// empty string.
// Deprecated: Use the index function instead.
func (ns *Namespace) EchoParam(c, k any) any {
helpers.Deprecated("collections.EchoParam", "Use the index function instead.", false)
hugo.Deprecate("collections.EchoParam", "Use the index function instead.", "v0.120.0")
av, isNil := indirect(reflect.ValueOf(c))
if isNil {
return ""

7
tpl/lang/lang.go
View file

@ -16,19 +16,18 @@ package lang
import (
"context"
"errors"
"fmt"
"math"
"strconv"
"strings"
"errors"
"github.com/gohugoio/locales"
translators "github.com/gohugoio/localescompressed"
"github.com/gohugoio/hugo/common/hreflect"
"github.com/gohugoio/hugo/common/hugo"
"github.com/gohugoio/hugo/deps"
"github.com/gohugoio/hugo/helpers"
"github.com/spf13/cast"
)
@ -243,7 +242,7 @@ func (ns *Namespace) FormatNumberCustom(precision, number any, options ...any) (
// Deprecated: Use lang.FormatNumberCustom instead.
func (ns *Namespace) NumFmt(precision, number any, options ...any) (string, error) {
helpers.Deprecated("lang.NumFmt", "Use lang.FormatNumberCustom instead.", false)
hugo.Deprecate("lang.NumFmt", "Use lang.FormatNumberCustom instead.", "v0.120.0")
return ns.FormatNumberCustom(precision, number, options...)
}