diff --git a/docs/.gitbook/assets/Tellor.png b/docs/.gitbook/assets/Tellor.png deleted file mode 100644 index 2c227053..00000000 Binary files a/docs/.gitbook/assets/Tellor.png and /dev/null differ diff --git a/docs/.gitbook/assets/minerspecs.png b/docs/.gitbook/assets/minerspecs.png deleted file mode 100644 index fd0bb9e9..00000000 Binary files a/docs/.gitbook/assets/minerspecs.png and /dev/null differ diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md new file mode 100755 index 00000000..d93eb6a7 --- /dev/null +++ b/docs/CHANGELOG.md @@ -0,0 +1,24 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) +and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). + +NOTE: As semantic versioning states all 0.y.z releases can contain breaking changes in API (flags, grpc API, any backward compatibility) + +We use *breaking :warning:* to mark changes that are not backward compatible (relates only to v0.y.z releases.) + +## Unreleased +- [#272](https://github.com/tellor-io/telliot/pull/272) Automated Docker images on every push to master and with every tagged release. + +## [v5.2.0](https://github.com/tellor-io/telliot/releases/tag/v5.2.0) - 2020.11.12 +- [#254](https://github.com/tellor-io/telliot/pull/254) + - Added support for expanding variables in the indexer api url. + - Added config to specify the `.env` file location. The default is now `configs/.env` so users should either specify a custom location in the `config.json` or move it inside the default config folder. + +## [v5.0.0](https://github.com/tellor-io/telliot/releases/tag/v5.0.0) - 2020.11.02 + +### Added + - Profitability calculations which is set through the `ProfitThreshold`(in percents) settings in the config, + - Docs how to contribute. diff --git a/docs/README.md b/docs/README.md old mode 100644 new mode 100755 index 00d0e4bb..39960270 --- a/docs/README.md +++ b/docs/README.md @@ -1,50 +1,63 @@ -# Introduction - [![tellor.io](.gitbook/assets/Tellor.png)](https://www.tellor.io/) +
+ + + +
- [![Twitter WeAreTellor](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/WeAreTellor) ++ + + +
-> ### ⚠️ Note! -> -> Telliot docs are synced from the project repository. To edit please visit: -> [Telliot gitbook space](https://docs.tellor.io/telliot) -> or -> [Telliot github repo](https://github.com/tellor-io/telliot/tree/master/docs) -## Telloit +> ## ⚠️ Note! +> Telliot docs are synced from the project repository. +To edit please visit:+ +
-Contributions are very welcome! - See our [04\_contributing.md](telliot-documentation/contributing.md) for more information. -### Run with Docker +## Instructions for deployment + - [Telliot Instructions](docs/setup-and-usage.md) -Available tags: [https://hub.docker.com/u/tellor](https://hub.docker.com/u/tellor) docker run -v $\(pwd\)/.local:/configs tellor/telliot:master mine +## Contributing and building from source +Contributions are very welcome!Better 🤓
-Better 🤓 - +---- ```go func writeToFile(...) (err error) { f, err := os.Open(...) @@ -93,16 +104,19 @@ func writeToFile(...) (err error) { } ``` -**Exhaust Readers** +#### Exhaust Readers -One of the most common bugs is forgetting to close or fully read the bodies of HTTP requests and responses, especially on error. If you read the body of such structures, you can use the [runutil](https://pkg.go.dev/github.com/thanos-io/thanos@v0.11.0/pkg/runutil?tab=doc) helper as well: +One of the most common bugs is forgetting to close or fully read the bodies of HTTP requests and responses, especially on +error. If you read the body of such structures, you can use the [runutil](https://pkg.go.dev/github.com/thanos-io/thanos@v0.11.0/pkg/runutil?tab=doc) +helper as well: ```go defer runutil.ExhaustCloseWithLogOnErr(logger, resp.Body, "close response") ``` -Avoid 🔥 +Avoid 🔥
+---- ```go resp, err := http.Get("http://example.com/") if err != nil { @@ -117,8 +131,9 @@ scanner := bufio.NewScanner(resp.Body) for scanner.Scan() { ``` -Better 🤓 +Better 🤓
+---- ```go resp, err := http.Get("http://example.com/") if err != nil { @@ -132,24 +147,30 @@ scanner := bufio.NewScanner(resp.Body) for scanner.Scan() { ``` -**Avoid Globals** -No globals other than `const` are allowed. Period. This means also, no `init` functions. +#### Avoid Globals -**Never Use Panics** +No globals other than `const` are allowed. Period. +This means also, no `init` functions. -Never use them. If some dependency uses it, use [recover](https://golang.org/doc/effective_go.html#recover). Also, consider avoiding that dependency. 🙈 +#### Never Use Panics -**Avoid Using the reflect or unsafe Packages** +Never use them. If some dependency uses it, use [recover](https://golang.org/doc/effective_go.html#recover). Also, consider +avoiding that dependency. 🙈 + +#### Avoid Using the `reflect` or `unsafe` Packages Use those only for very specific, critical cases. Especially `reflect` tend to be very slow. For testing code, it's fine to use reflect. -**Avoid variable shadowing** +#### Avoid variable shadowing -Variable shadowing is when you use the same variable name in a smaller scope that "shadows". This is very dangerous as it leads to many surprises. It's extremely hard to debug such problems as they might appear in unrelated parts of the code. And what's broken is tiny `:` or lack of it. +Variable shadowing is when you use the same variable name in a smaller scope that "shadows". This is very +dangerous as it leads to many surprises. It's extremely hard to debug such problems as they might appear in unrelated parts of the code. +And what's broken is tiny `:` or lack of it. -Avoid 🔥 +Avoid 🔥
+---- ```go var client ClientInterface if clientTypeASpecified { @@ -169,8 +190,9 @@ Avoid 🔥 resp, err := client.Call(....) // nil pointer panic! ``` -Better 🤓 +Better 🤓
+---- ```go var client ClientInterface = NewNoop(...) if clientTypeASpecified { @@ -193,24 +215,32 @@ This is also why we recommend to scope errors if you can: } ``` -While it's not yet configured, we might think consider not permitting variable shadowing with [`golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow`](https://godoc.org/golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow) in future. There was even Go 2 proposal for [disabling this in the language itself, but was rejected](https://github.com/golang/go/issues/21114): +While it's not yet configured, we might think consider not permitting variable shadowing with [`golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow`](https://godoc.org/golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow) +in future. There was even Go 2 proposal for [disabling this in the language itself, but was rejected](https://github.com/golang/go/issues/21114): Similar to this problem is the package name shadowing. While it is less dangerous, it can cause similar issues, so avoid package shadowing if you can. -#### Performance +### Performance -After all better performance is important and this might require some additional patterns in our code. With those patterns, we try to not sacrifice the readability and apply those only on the critical code paths. +After all better performance is important and this might require some additional patterns in our code. With those patterns, we try to not sacrifice the readability and apply those only +on the critical code paths. -**Keep in mind to always measure the results.** The Go performance relies on many hidden things and tweaks, so the good micro benchmark, following with the real system load test is in most times required to tell if optimization makes sense. +**Keep in mind to always measure the results.** The Go performance relies on many hidden things and tweaks, so the good +micro benchmark, following with the real system load test is in most times required to tell if optimization makes sense. -**Pre-allocating Slices and Maps** +#### Pre-allocating Slices and Maps -Try to always preallocate slices and map. If you know the number of elements you want to put apriori, use that knowledge! This significantly improves the latency of such code. Consider this as micro optimization, however, it's a good pattern to do it always, as it does not add much complexity. Performance wise, it's only relevant for critical, code paths with big arrays. +Try to always preallocate slices and map. If you know the number of elements you want to put +apriori, use that knowledge! This significantly improves the latency of such code. Consider this as micro optimization, +however, it's a good pattern to do it always, as it does not add much complexity. Performance wise, it's only relevant for critical, +code paths with big arrays. -NOTE: This is because, in very simple view, the Go runtime allocates 2 times the current size. So if you expect million of elements, Go will do many allocations on `append` in between instead of just one if you preallocate. +NOTE: This is because, in very simple view, the Go runtime allocates 2 times the current size. So if you expect million of elements, Go will do many allocations +on `append` in between instead of just one if you preallocate. -Avoid 🔥 +Avoid 🔥
+---- ```go func copyIntoSliceAndMap(biggy []string) (a []string, b map[string]struct{}) b = map[string]struct{}{} @@ -222,8 +252,9 @@ func copyIntoSliceAndMap(biggy []string) (a []string, b map[string]struct{}) } ``` -Better 🤓 +Better 🤓
+---- ```go func copyIntoSliceAndMap(biggy []string) (a []string, b map[string]struct{}) b = make(map[string]struct{}, len(biggy)) @@ -237,14 +268,20 @@ func copyIntoSliceAndMap(biggy []string) (a []string, b map[string]struct{}) } ``` -**Reuse arrays** +#### Reuse arrays -To extend the above point, there are cases where you don't need to allocate new space in memory all the time. If you repeat the certain operation on slices sequentially and you just release the array on every iteration, it's reasonable to reuse the underlying array for those. This can give quite enormous gains for critical paths. Unfortunately, currently there is no way to reuse the underlying array for maps. +To extend the above point, there are cases where you don't need to allocate new space in memory all the time. If you repeat +the certain operation on slices sequentially and you just release the array on every iteration, it's reasonable to reuse +the underlying array for those. This can give quite enormous gains for critical paths. +Unfortunately, currently there is no way to reuse the underlying array for maps. -NOTE: Why you cannot just allocate slice and release and in new iteration allocate and release again etc? Go should know it has available space and just reuses that no? \(: Well, it's not that easy. TL;DR is that Go Garbage Collection runs periodically or on certain cases \(big heap\), but definitely not on every iteration of your loop \(that would be super slow\). Read more in details [here](https://about.sourcegraph.com/go/gophercon-2018-allocator-wrestling). +NOTE: Why you cannot just allocate slice and release and in new iteration allocate and release again etc? Go should know it has +available space and just reuses that no? (: Well, it's not that easy. TL;DR is that Go Garbage Collection runs periodically or on certain cases +(big heap), but definitely not on every iteration of your loop (that would be super slow). Read more in details [here](https://about.sourcegraph.com/go/gophercon-2018-allocator-wrestling). -Avoid 🔥 +Avoid 🔥
+---- ```go var messages []string for _, msg := range recv { @@ -261,8 +298,9 @@ for _, msg := range recv { } ``` -Better 🤓 +Better 🤓
+---- ```go var messages []string for _, msg := range recv { @@ -278,22 +316,26 @@ for _, msg := range recv { } ``` -#### Readability +### Readability The part that all Gophers love ❤️ How to make code more readable? -For the Team, readability is about programming in a way that does not surprise the reader of the code. All the details and inconsistencies can distract or mislead the reader, so every character or newline might matter. That's why we might be spending more time on every Pull Requests' review, especially in the beginning, but for a good reason! To make sure we can quickly understand, extend and fix problems with our system. - -**Keep the Interface Narrow; Avoid Shallow Functions** +For the Team, readability is about programming in a way that does not surprise the reader of the code. All the details +and inconsistencies can distract or mislead the reader, so every character or newline might matter. That's why we might be spending +more time on every Pull Requests' review, especially in the beginning, but for a good reason! To make sure we can quickly understand, +extend and fix problems with our system. -This is connected more to the API design than coding, but even during small coding decisions it matter. For example how you define functions or methods. There are two general rules: +#### Keep the Interface Narrow; Avoid Shallow Functions -* Simpler \(usually it means smaller\) interfaces are better. This might mean a smaller, simpler function signature as well as fewer methods +This is connected more to the API design than coding, but even during small coding decisions it matter. For example how you define functions +or methods. There are two general rules: - in the interfaces. Try to group interfaces based on functionality to expose at max 1-3 methods if possible. +* Simpler (usually it means smaller) interfaces are better. This might mean a smaller, simpler function signature as well as fewer methods +in the interfaces. Try to group interfaces based on functionality to expose at max 1-3 methods if possible. -Avoid 🔥 +Avoid 🔥
+---- ```go // Compactor aka: The Big Boy. Such big interface is really useless ): type Compactor interface { @@ -310,8 +352,9 @@ type Compactor interface { } ``` -Better 🤓 +Better 🤓
+---- ```go // Smaller interfaces with a smaller number of arguments allow functional grouping, clean composition and clear testability. type Compactor interface { @@ -344,14 +387,14 @@ type Cleaner interface { } ``` -* It's better if you can hide more unnecessary complexity from the user. This means that having shallow function introduce - - more cognitive load to understand the function name or navigate to implementation to understand it better. It might be much - more readable to inline those few lines directly on the caller side. +* It's better if you can hide more unnecessary complexity from the user. This means that having shallow function introduce +more cognitive load to understand the function name or navigate to implementation to understand it better. It might be much +more readable to inline those few lines directly on the caller side. -Avoid 🔥 +Avoid 🔥
+---- ```go // Some code... s.doSomethingAndHandleError() @@ -366,8 +409,9 @@ func (s *myStruct) doSomethingAndHandleError() { } ``` -Better 🤓 +Better 🤓
+---- ```go // Some code... if err := doSomething(); err != nil { @@ -378,10 +422,13 @@ Better 🤓 } ``` -This is a little bit connected to `There should be one-- and preferably only one --obvious way to do it` and [`DRY`](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) rules. If you have more ways of doing something than one, it means you have a wider interface, allowing more opportunities for errors, ambiguity and maintenance burden. +This is a little bit connected to `There should be one-- and preferably only one --obvious way to do it` and [`DRY`](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) +rules. If you have more ways of doing something than one, it means you have a wider interface, allowing more opportunities for +errors, ambiguity and maintenance burden. -Avoid 🔥 +Avoid 🔥
+---- ```go // We have here SIX potential ways the caller can get an ID. Can you find all of them? @@ -405,8 +452,9 @@ func (b *Block) ID() ulid.ULID { func (b *Block) IDNoLock() ulid.ULID { return b.ID } ``` -Better 🤓 +Better 🤓
+---- ```go type Block struct { // Things... @@ -422,18 +470,22 @@ func (b *Block) ID() ulid.ULID { } ``` -**Use Named Return Parameters Carefully** +#### Use Named Return Parameters Carefully -It's OK to name return parameters if the types do not give enough information about what function or method actually returns. Another use case is when you want to define a variable, e.g. a slice. +It's OK to name return parameters if the types do not give enough information about what function or method actually returns. +Another use case is when you want to define a variable, e.g. a slice. -**IMPORTANT:** never use naked `return` statements with named return parameters. This compiles but it makes returning values implicit and thus more prone to surprises. +**IMPORTANT:** never use naked `return` statements with named return parameters. This compiles but it makes returning values +implicit and thus more prone to surprises. -**Clean Defer Only if Function Fails** +#### Clean Defer Only if Function Fails -There is a way to sacrifice defer in order to properly close all on each error. Repetition makes it easier to make an error and forget something when changing the code, so on-error deferring is doable: +There is a way to sacrifice defer in order to properly close all on each error. Repetition makes it easier to make an error +and forget something when changing the code, so on-error deferring is doable: -Avoid 🔥 +Avoid 🔥
+---- ```go func OpenSomeFileAndDoSomeStuff() (*os.File, error) { f, err := os.OpenFile("file.txt", os.O_RDONLY, 0) @@ -457,8 +509,9 @@ func OpenSomeFileAndDoSomeStuff() (*os.File, error) { } ``` -Better 🤓 +Better 🤓
+---- ```go func OpenSomeFileAndDoSomeStuff() (f *os.File, err error) { f, err = os.OpenFile("file.txt", os.O_RDONLY, 0) @@ -484,30 +537,37 @@ func OpenSomeFileAndDoSomeStuff() (f *os.File, err error) { } ``` -**Explicitly Handle Returned Errors** +#### Explicitly Handle Returned Errors -Always handle returned errors. It does not mean you cannot "ignore" the error for some reason, e.g. if we know implementation will not return anything meaningful. You can ignore the error, but do so explicitly: +Always handle returned errors. It does not mean you cannot "ignore" the error for some reason, e.g. if we know implementation +will not return anything meaningful. You can ignore the error, but do so explicitly: -Avoid 🔥 +Avoid 🔥
+---- ```go someMethodThatReturnsError(...) ``` -Better 🤓 +Better 🤓
+---- ```go _ = someMethodThatReturnsError(...) ``` + The exception: well-known cases such as `level.Debug|Warn` etc and `fmt.Fprint*` -**Avoid Defining Variables Used Only Once.** +#### Avoid Defining Variables Used Only Once. -It's tempting to define a variable as an intermittent step to create something bigger. Avoid defining such a variable if it's used only once. When you create a variable _the reader_ expects some other usage of this variable than one, so it can be annoying to every time double check that and realize that it's only used once. +It's tempting to define a variable as an intermittent step to create something bigger. Avoid defining +such a variable if it's used only once. When you create a variable *the reader* expects some other usage of this variable than +one, so it can be annoying to every time double check that and realize that it's only used once. -Avoid 🔥 +Avoid 🔥
+---- ```go someConfig := a.GetConfig() address124 := someConfig.Addresses[124] @@ -517,8 +577,9 @@ Avoid 🔥 return c ``` -Better 🤓 +Better 🤓
+---- ```go // This variable is required for potentially consistent results. It is used twice. someConfig := a.FetchConfig() @@ -528,12 +589,13 @@ Better 🤓 } ``` -**Only Two Ways of Formatting Functions/Methods** +#### Only Two Ways of Formatting Functions/Methods Prefer function/method definitions with arguments in a single line. If it's too wide, put each argument on a new line. -Avoid 🔥 +Avoid 🔥
+---- ```go func function(argument1 int, argument2 string, argument3 time.Duration, argument4 someType, @@ -541,8 +603,9 @@ func function(argument1 int, argument2 string, ) (ret int, err error) { ``` -Better 🤓 +Better 🤓
+---- ```go func function( argument1 int, @@ -556,7 +619,7 @@ func function( This applies for both calling and defining method / function. -NOTE: One exception would be when you expect the variadic \(e.g. `...string`\) arguments to be filled in pairs, e.g: +NOTE: One exception would be when you expect the variadic (e.g. `...string`) arguments to be filled in pairs, e.g: ```go level.Info(logger).Log( @@ -567,12 +630,14 @@ level.Info(logger).Log( ) ``` -**Control Structure: Prefer early returns and avoid else** +#### Control Structure: Prefer early returns and avoid `else` -In most of the cases, you don't need `else`. You can usually use `continue`, `break` or `return` to end an `if` block. This enables having one less indent and better consistency so code is more readable. +In most of the cases, you don't need `else`. You can usually use `continue`, `break` or `return` to end an `if` block. +This enables having one less indent and better consistency so code is more readable. -Avoid 🔥 +Avoid 🔥
+---- ```go for _, elem := range elems { if a == 1 { @@ -583,8 +648,9 @@ for _, elem := range elems { } ``` -Better 🤓 +Better 🤓
+---- ```go for _, elem := range elems { if a == 1 { @@ -595,41 +661,47 @@ for _, elem := range elems { } ``` -**Wrap Errors for More Context; Don't Repeat "failed ..." There.** +#### Wrap Errors for More Context; Don't Repeat "failed ..." There. -We use [`pkg/errors`](https://github.com/pkg/errors) package for `errors`. We prefer it over standard wrapping with `fmt.Errorf` + `%w`, as `errors.Wrap` is explicit. It's easy to by accident replace `%w` with `%v` or to add extra inconsistent characters to the string. +We use [`pkg/errors`](https://github.com/pkg/errors) package for `errors`. We prefer it over standard wrapping with `fmt.Errorf` + `%w`, +as `errors.Wrap` is explicit. It's easy to by accident replace `%w` with `%v` or to add extra inconsistent characters to the string. -Use [`pkg/errors.Wrap`](https://github.com/pkg/errors) to wrap errors for future context when errors occur. It's recommended to add more interesting variables to add context using `errors.Wrapf`, e.g. file names, IDs or things that fail, etc. +Use [`pkg/errors.Wrap`](https://github.com/pkg/errors) to wrap errors for future context when errors occur. It's recommended +to add more interesting variables to add context using `errors.Wrapf`, e.g. file names, IDs or things that fail, etc. When using `Errorf,Warpf` put arguments at the end to make it easyer to read and use `%v` to reduce human error if the argument type changed. +Difficult to read 🔥
-Difficult to read 🔥 - +---- ```go errors.Errorf("insufficient balance %s, mining stake requires %s", a, b) ``` -Better 🤓 +Better 🤓
+---- ```go errors.Errorf("insufficient mining stake TRB balance - actual:%v, required:%v", a, b) ``` -NOTE: never prefix wrap messages with wording like `failed...`, `couldn't...` or `error occurred while...`. Just describe what we wanted to do when the failure occurred. Those prefixes are just noise. We are wrapping error, so it's obvious that some error occurred, right? \(: Improve readability and consider avoiding those. +NOTE: never prefix wrap messages with wording like `failed...`, `couldn't...` or `error occurred while...`. Just describe what we +wanted to do when the failure occurred. Those prefixes are just noise. We are wrapping error, so it's obvious that some error +occurred, right? (: Improve readability and consider avoiding those. -Avoid 🔥 +Avoid 🔥
+---- ```go fmt.Errorf("error while reading from file %s: %w", f.Name, err) ``` -Better 🤓 +Better 🤓
+---- ```go errors.Wrapf(err, "read file %s", f.Name) ``` - -**Use the Blank Identifier \_** +#### Use the Blank Identifier `_` Blank identifiers are very useful to mark variables that are not used. Consider the following cases: @@ -654,19 +726,25 @@ var _ InterfaceA = TypeA func (t *Type) SomeMethod(_ context.Context, abc int) error { ``` -**Rules for Log Messages** +#### Rules for Log Messages -The project uses [go-kit logger](https://github.com/go-kit/kit/tree/master/log). This means that we expect log lines to have a certain structure. Structure means that instead of adding variables to the message, those should be passed as separate fields. Keep in mind that all log lines should be `lowercase` \(readability and consistency\) and all struct keys are using `camelCase`. It's suggested to keep key names short and consistent. For example, if we always use `block` for block ID, let's not use in the other single log message `id`. +The project uses [go-kit logger](https://github.com/go-kit/kit/tree/master/log). This means that we expect log lines +to have a certain structure. Structure means that instead of adding variables to the message, those should be passed as +separate fields. Keep in mind that all log lines should be `lowercase` (readability and consistency) and +all struct keys are using `camelCase`. It's suggested to keep key names short and consistent. For example, if +we always use `block` for block ID, let's not use in the other single log message `id`. -Avoid 🔥 +Avoid 🔥
+---- ```go level.Info(logger).Log("msg", fmt.Sprintf("Found something epic during compaction number %v. This looks amazing.", compactionNumber), "block_id", id, "elapsed-time", timeElapsed) ``` -Better 🤓 +Better 🤓
+---- ```go level.Info(logger).Log("msg", "found something epic during compaction; this looks amazing", "compNumber", compNumber, "block", id, "elapsed", timeElapsed) @@ -675,31 +753,30 @@ level.Info(logger).Log("msg", "found something epic during compaction; this look Additionally, there are certain rules we suggest while using different log levels: * level.Info: Should always have `msg` field. It should be used only for important events that we expect to happen not too - - often. - +often. * level.Debug: Should always have `msg` field. It can be a bit more spammy, but should not be everywhere as well. Use it - - only when you want to really dive into some problems in certain areas. - +only when you want to really dive into some problems in certain areas. * level.Warn: Should have either `msg` or `err` or both fields. They should warn about events that are suspicious and to investigate - - but the process can gracefully mitigate it. Always try to describe _how_ it was mitigated, what action will be performed e.g. `value will be skipped` - +but the process can gracefully mitigate it. Always try to describe *how* it was mitigated, what action will be performed e.g. `value will be skipped` * level.Error: Should have either `msg` or `err` or both fields. Use it only for a critical event. -**Comment Necessary Surprises** +#### Comment Necessary Surprises -Comments are not the best. They age quickly and the compiler does not fail if you will forget to update them. So use comments only when necessary. **And it is necessary to comment on code that can surprise the user.** Sometimes, complexity is necessary, for example for performance. Comment in this case why such optimization was needed. If something was done temporarily add `TODO(Avoid 🔥
+---- ```go host, port, err := net.SplitHostPort("1.2.3.4:1234") testutil.Ok(t, err) @@ -720,7 +797,9 @@ host, port, err = net.SplitHostPort("yolo") testutil.NotOk(t, err) ``` -Better 🤓 +Better 🤓
+ +---- ```go for _, tcase := range []struct{ @@ -774,12 +853,14 @@ for _, tcase := range []struct{ } ``` -**Tests for Packages / Structs That Involve time package.** +#### Tests for Packages / Structs That Involve `time` package. -Avoid unit testing based on real-time. Always try to mock time that is used within struct by using, for example, a `timeNow func() time.Time` field. For production code, you can initialize the field with `time.Now`. For test code, you can set a custom time that will be used by the struct. +Avoid unit testing based on real-time. Always try to mock time that is used within struct by using, for example, a `timeNow func() time.Time` field. +For production code, you can initialize the field with `time.Now`. For test code, you can set a custom time that will be used by the struct. -Avoid 🔥 +Avoid 🔥
+---- ```go func (s *SomeType) IsExpired(created time.Time) bool { // Code is hardly testable. @@ -787,8 +868,9 @@ func (s *SomeType) IsExpired(created time.Time) bool { } ``` -Better 🤓 +Better 🤓
+---- ```go func (s *SomeType) IsExpired(created time.Time) bool { // s.timeNow is time.Now on production, mocked in tests. @@ -796,21 +878,21 @@ func (s *SomeType) IsExpired(created time.Time) bool { } ``` -### Enforced by Linters +## Enforced by Linters -This is the list of rules we ensure automatically. This section is for those who are curious why such linting rules were added or want similar ones in their Go project. 🤗 +This is the list of rules we ensure automatically. This section is for those who are curious why such linting rules +were added or want similar ones in their Go project. 🤗 -**Avoid Prints** +#### Avoid Prints Never use `print`. Always use a passed `go-kit/log.Logger`. -**Comments Should be Full Sentences** +#### Comments Should be Full Sentences All comments should be full sentences. They should start with an uppercase letter and end with a period. -## Bash +# Bash Overall try to NOT use bash. For scripts longer than 30 lines, consider writing it in Go as we did [here](https://github.com/tellor-io/telliot/blob/e502c668c0f76aa4d382eadcb7d3f0c26cfee9fb/scripts/copyright/copyright.go). -If you have to, we follow the Google Shell style guide: [https://google.github.io/styleguide/shellguide.html](https://google.github.io/styleguide/shellguide.html) - +If you have to, we follow the Google Shell style guide: https://google.github.io/styleguide/shellguide.html diff --git a/docs/telliot-documentation/configuation.md b/docs/configuation.md similarity index 97% rename from docs/telliot-documentation/configuation.md rename to docs/configuation.md index 691ff986..da58991c 100644 --- a/docs/telliot-documentation/configuation.md +++ b/docs/configuation.md @@ -1,13 +1,9 @@ --- description: Telliot tweaks and settings to keep your rig running smoothly. --- - -# Configuation - +# Telliot configuration ## Cli reference - Telliot commands and config file options are as the following: - #### Required Flags * `--config` \(path to your config file.\) @@ -29,7 +25,7 @@ Telliot commands and config file options are as the following: #### Config file options: * `contractAddress` \(required\) - address of TellorContract -* `nodeURL` \(required\) - node URL \(e.g [https://mainnet.infura.io/bbbb](https://mainnet.infura.io/bbbb) or [https://localhost:8545](https://localhost:8545) if own node\) +* `nodeURL` \(required\) - node URL \(e.g https://mainnet.infura.io/bbbb or https://localhost:8545 if own node\) * `privateKey` \(required\) - privateKey for your address * `databaseURL` \(required\) - where you are reading from for the server database \(if hosted\) * `publicAddress` \(required\) - public address for your miner \(note, no 0x\) @@ -162,6 +158,7 @@ Note that your dataServer and miners must be started with separate commands. For more detailed instructions:[ https://docs.google.com/document/d/1k8ELb1cXkEpztHkHUt8QTL4JCcnHw5\_yQjTKIHCaSCE](https://docs.google.com/document/d/1k8ELb1cXkEpztHkHUt8QTL4JCcnHw5_yQjTKIHCaSCE) + ### LogConfig file options The logging.config file consists of two fields: \* component \* level @@ -178,5 +175,4 @@ INFO - logs most information about the mining operation WARN - logs all warnings and errors -ERROR - logs only serious errors - +ERROR - logs only serious errors \ No newline at end of file diff --git a/docs/telliot-documentation/contributing.md b/docs/contributing.md old mode 100644 new mode 100755 similarity index 61% rename from docs/telliot-documentation/contributing.md rename to docs/contributing.md index 21a5f957..ce671d24 --- a/docs/telliot-documentation/contributing.md +++ b/docs/contributing.md @@ -5,48 +5,38 @@ description: Process of contributing to the project. # Contributing ## Philosophy - -* The philosophy is borrowing much from UNIX philosophy and the golang programming language.Each sub command should do one thing and do it well - * Every component behaviour should be covered with an e2e tests and if an e2e tests is not appropriate should at least have unit tests for key components of a package. +- The philosophy is borrowing much from UNIX philosophy and the golang programming language.Each sub command should do one thing and do it well + - Every component behaviour should be covered with an e2e tests and if an e2e tests is not appropriate should at least have unit tests for key components of a package. ## Feedback / Issues - If you encounter any issue or you have an idea to improve, please: * Search through Google and [existing open and closed GitHub Issues](https://github.com/tellor-io/telliot/issues) for the - - answer first. If you find relevant topic, please comment on the issue. - +answer first. If you find relevant topic, please comment on the issue. * If not found, please add an issue to [GitHub issues](https://github.com/tellor-io/telliot/issues). Please provide - - all relevant information as template suggest. - +all relevant information as template suggest. * If you have a quick question you might want to also ask on our [Discord](https://discord.gg/n7drGjh). - - We are recommending, using GitHub issues for issues and feedback, because GitHub issues are track-able. +We are recommending, using GitHub issues for issues and feedback, because GitHub issues are track-able. If you encounter security vulnerability, please let us know privately via the Team email address: [info@tellor.io](mailto:info@tellor.io?subject=Security%20vulnerability%20report) ## Adding New Features / Components - -For any major changes or new features, please first discuss the change you wish to make via issue or Discord, or any other method before making a change. +For any major changes or new features, please first +discuss the change you wish to make via issue or Discord, or any other +method before making a change. ## Development - The following section explains various suggestions and procedures to note during development. ### First Steps - * Familiarizing yourself with our [coding style guidelines.](coding-style-guide.md). -* Familiarizing yourself with the [Makefile](https://github.com/tellor-io/telliot/tree/4b4e37cbbd76473f59261ae9790918446cc5114c/Makefile/README.md) commands, for example, `build`, `format`, `test`, `lint`. - - `make help` will print all available commands with some description. +* Familiarizing yourself with the [Makefile](../Makefile) commands, for example, `build`, `format`, `test`, `lint`. +`make help` will print all available commands with some description. ### Pull Request Process - 1. Fork tellor-io/telliot.git and start development from your own fork. Here are sample steps to setup your development environment: -```text +```console $ GOPATH=$(go env GOPATH) $ mkdir -p $GOPATH/src/github.com/tellor-io $ cd $GOPATH/src/github.com/tellor-io @@ -57,11 +47,11 @@ $ make build $ ./telliot -h ``` -1. Keep PRs as small as possible. For each of your PRs, you create a new branch based on the latest master. - Chain them if needed \(base one PR on other PRs\). You can read more details about the workflow from [here](https://gist.github.com/Chaser324/ce0505fbed06b947d962). +1. Keep PRs as small as possible. For each of your PRs, you create a new branch based on the latest master. +Chain them if needed (base one PR on other PRs). You can read more details about the workflow from [here](https://gist.github.com/Chaser324/ce0505fbed06b947d962). -```text +```console $ git checkout master $ git pull origin master $ git checkout -b