Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
78 lines (57 loc) · 3.75 KB

CONTRIBUTING.md

File metadata and controls

78 lines (57 loc) · 3.75 KB

Contributing

Code contributions are always welcome in lf.

If you are going to introduce a new feature, it is best to open an issue first for discussion. You should also consider the following:

  • Whether it can be implemented entirely in user configuration instead
  • The complexity added by supporting it
  • The number of users interested in it

If your feature can be implemented as a configuration option, please add it to the wiki.

For bug fixes, you can simply send a pull request.

Code conventions

In addition to gofmt and friends (e.g. go vet, staticcheck, golangci-lint), we have a few conventions:

  • Global variables are best avoided except when they are not. Global variable names are prefixed with g as in gFooBar. Exceptions are variables that store values of environment variables, which are prefixed with env as in envFooBar, and regular expressions, which are prefixed with re as in reFooBar when they are global.
  • Type and function names are lowercase as in fooBar since we don't use exporting.
  • For filename variables, name, fname, or filename should refer to the base name of the file as in baz.txt, and path, fpath, or filepath should refer to the full path of the file as in /foo/bar/baz.txt.
  • Run go fmt to ensure that files are formatted correctly.
  • Consider using conventional commit messages.

Use the surrounding code as reference when in doubt as usual.

Adding a new option

Adding a new option usually requires the following steps:

  • Add option name/type to gOpts struct in opts.go
  • Add default option value to init function in opts.go
  • Add option evaluation logic to setExpr.eval in eval.go
  • Implement the option somewhere in the code
  • Add option name and its default value to Quick Reference and Settings sections in doc.md
  • Run gen/doc.sh to update the documentation (optional as it requires docker/podman, but appreciated)
  • Commit your changes and send a pull request

Options should be defined in alphabetical order, but note that boolean options are defined first in eval.go as they require special handling.

Adding a new builtin command

Adding a new command usually requires the following steps:

  • Add default key if any to init function in opts.go
  • Add command evaluation logic to callExpr.eval in eval.go
  • Implement the command somewhere in the code
  • Add command name to gCmdWords in complete.go for tab completion
  • Add command name to Quick Reference and Commands sections in doc.md
  • Run gen/doc.sh to update the documentation (optional as it requires docker/podman, but appreciated)
  • Commit your changes and send a pull request

Commands should be defined in alphabetical order, but note that commands are first organized roughly into the following sections in eval.go for clarity:

  • Navigation
  • Selection
  • File-related operations
  • Shell commands
  • Finding and searching
  • Filtering
  • Marks
  • Tags
  • Echoing
  • Miscellaneous commands
  • Visual mode
  • Command-line mode commands
  • Hook commands

Platform specific code

There are two files named os.go and os_windows.go for Unix and Windows specific code respectively. If you add something to either of these files but not the other, you will probably break the build for the other platform. If your addition works the same on both platforms, your addition probably belongs to main.go instead.

There are also different variants of the df functionality provided by df_openbsd.go, df_statfs.go, df_statvfs.go and df_windows.go. Where applicable, ensure that any changes you make are reflected across all of these files for consistency.