@@ -11,89 +11,154 @@ You may also use it standalone for your projects.
1111
1212> ` swag ` is one of the foundational building blocks of the go-openapi initiative.
1313>
14- > Most packages in ` github.com/go-openapi/... ` depend on it in some way.
14+ > Most repositories in ` github.com/go-openapi/... ` depend on it in some way.
1515> So does the CLI tool ` github.com/go-swagger/go-swagger ` ,
1616> and the code generated by this tool.
1717
1818## Contents
1919
20+ ` go-openapi/swag ` now exposes a collection of relatively independent modules.
21+
2022Here is what is inside:
2123
22- * Package ` conv `
24+ * Module ` cmdutils `
25+
26+ * [x] utilities to work with CLIs
27+
28+ * Module ` conv `
2329
2430 * [x] convert between values and pointers for any types
2531 * [x] convert from string to builtin types (wraps ` strconv ` )
32+ * [x] require ` ./typeutils ` (test dependency)
2633
27- * Package ` fileutils `
34+ * Module ` fileutils `
2835
2936 * [x] file upload type
3037 * [x] search in path (deprecated)
31- * Package ` jsonname `
38+
39+ * Module ` jsonname `
3240
3341 * [x] infer JSON names from go properties
3442
35- * Package ` jsonutils `
43+ * Module ` jsonutils `
3644
3745 * [x] fast json concatenation
3846 * [x] read and write JSON from and to dynamic go data structures
47+ * [x] require ` github.com/mailru/easyjson `
3948
40- * Package ` loading `
49+ * Module ` loading `
4150
4251 * [x] load from file or http
52+ * [x] require ` ./yamlutils `
4353
44- * Package ` mangling `
54+ * Module ` mangling `
4555
4656 * [x] name mangling for go
4757
48- * Package ` netutils `
58+ * Module ` netutils `
4959
5060 * [x] host, port from address
5161
52- * Package ` stringutils `
62+ * Module ` stringutils `
5363
5464 * [x] search in slice (with case-insensitive)
55- * [x] slit /join query parameters as arrays
65+ * [x] split /join query parameters as arrays
5666
57- * Package ` typeutils `
67+ * Module ` typeutils `
5868
5969 * [x] check the zero value for any type
6070
61- * Package ` yamlutils `
71+ * Module ` yamlutils `
6272
6373 * [x] converting YAML to JSON
6474 * [x] loading YAML into a dynamic YAML document
75+ * [x] require ` ./jsonutils `
76+ * [x] require ` github.com/mailru/easyjson `
77+ * [x] require ` gopkg.in/yaml.v3 `
6578
6679---
6780
68- This repo has a few dependencies outside of the standard library:
81+ The root module ` github.com/go-openapi/swag ` at the repo level maintains a few
82+ dependencies outside of the standard library:
6983
7084* YAML utilities depend on ` gopkg.in/yaml.v3 `
7185* JSON utilities ` github.com/mailru/easyjson `
7286
87+ This is not necessarily the case for all sub-modules.
88+
7389## Release notes
7490
75- ### v0.24.0
91+ ### v0.24.0 [ Unreleased ]
7692
7793With this release, we have largely modernized the API of ` swag ` :
78- * The traditional ` swag ` API still works the same: code that imports ` swag ` will still
94+
95+ * The traditional ` swag ` API is still supported: code that imports ` swag ` will still
7996 compile and work the same.
8097* A deprecation notice is published to encourage consumers of this library to adopt
81- the newer API:
98+ the newer API
99+ * ** Deprecation notice**
82100 * configuration through global variables is now deprecated, in favor of options passed as parameters
83- * helper functions are moved to more specialized packages, which are exposed as
101+ * all helper functions are moved to more specialized packages, which are exposed as
84102 go modules. Importing such a module would reduce the footprint of dependencies.
85-
86- Moving forward, no additional feature will be added to the ` swag ` API directly.
87- However, child modules will continue to evolve or some new ones may be added in the future .
103+ * _ all _ functions, variables, constants exposed by the deprecated API have now moved, so
104+ that consumers of the new API no longer need to import github.com/go-openapi/swag, but
105+ should import the desired sub-module(s) .
88106
89107** New with this release** :
90108
91109* [x] type converters and pointer to value helpers now support generic types
92110* [x] name mangling now support pluralized initialisms (issue #46 )
93- Strings like "contact IDs" are now recognized as such a plural form and
111+ Strings like "contact IDs" are now recognized as such a plural form and mangled as a linter would expect.
94112* [x] performance: small improvements to reduce the overhead of convert/format wrappers (see issues #110 , or PR #108 )
95113* [x] performance: name mangling utilities run ~ 10% faster (PR #115 )
96114
115+ ---
116+
117+ Moving forward, no additional feature will be added to the ` swag ` API directly.
118+
119+ However, child modules will continue to evolve or some new ones may be added in the future.
120+
121+
122+ #### Note to contributors
123+
124+ The mono-repo structure comes with some unavoidable extra pains...
125+
126+ * Testing
127+
128+ > The usual ` go test ./... ` command, run from the root of this repo won't work any longer to test all submodules.
129+ >
130+ > Each module constitutes an independant unit of test. So you have to run ` go test ` inside each module.
131+ > Or you may take a look at how this is achieved by CI
132+ > [ here] https://github.com/go-openapi/swag/blob/master/.github/workflows/go-test.yml ).
133+ >
134+ > There are also some alternative tricks using ` go work ` , for local development, if you feel comfortable with
135+ > go workspaces. Perhaps some day, we'll have a ` go work test ` to run all tests without any hack.
136+
137+ * Releasing
138+
139+ > Each module follows its own independant module versioning.
140+ >
141+ > So you have tags like ` mangling/v0.24.0 ` , ` fileutils/v0.24.0 ` etc that are used by ` go mod ` and ` go get `
142+ > to refer to the tagged version of each module specifically.
143+ >
144+ > This means we may release patches etc to each module independently.
145+ >
146+ > We'd like to adopt the rule that modules in this repo would only differ by a patch version
147+ > (e.g. ` v0.24.5 ` vs ` v0.24.3 ` ), and we'll level all modules whenever a minor version is introduced.
148+ >
149+ > A script in ` ./hack ` is provided to tag all modules in one go at the same level in one go.
150+
97151## Todos, suggestions and plans
98152
99153All kinds of contributions are welcome.
154+
155+ A few ideas:
156+
157+ * [ ] Complete the split of dependencies to isolate easyjson from the rest
158+ * [ ] Improve mangling utilities (improve readability, support for capitalized words,
159+ better word substitution for non-letter symbols...)
160+ * [ ] Move back to this common shared pot a few of the technical features introduced by go-swagger independently
161+ (e.g. mangle go package names, search package with go modules support, ...)
162+ * [ ] Apply a similar mono-repo approach to go-openapi/strfmt which suffer from similar woes: bloated API,
163+ imposed dependency to some database driver.
164+
0 commit comments