-
-
Notifications
You must be signed in to change notification settings - Fork 35
/
doc.go
161 lines (161 loc) · 6.52 KB
/
doc.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
// Package podcast generates a fully compliant iTunes and RSS 2.0 podcast feed
// for GoLang using a simple API.
//
// Full documentation with detailed examples located at https://godoc.org/github.com/eduncan911/podcast
//
// Usage
//
// To use, `go get` and `import` the package like your typical GoLang library.
//
// $ go get -u github.com/eduncan911/podcast
//
// import "github.com/eduncan911/podcast"
//
// The API exposes a number of method receivers on structs that implements the
// logic required to comply with the specifications and ensure a compliant feed.
// A number of overrides occur to help with iTunes visibility of your episodes.
//
// Notably, the `Podcast.AddItem` function performs most
// of the heavy lifting by taking the `Item` input and performing
// validation, overrides and duplicate setters through the feed.
//
// Full detailed Examples of the API are at https://godoc.org/github.com/eduncan911/podcast.
//
// Contributing
//
// See the CONTRIBUTING.md for all the details.
//
// Go Modules
//
// This library is supported on GoLang 1.7 and higher.
//
// We have implemented Go Modules support and the CI pipeline shows it working with
// new installs, tested with Go 1.13. To keep 1.7 compatibility, we use
// `go mod vendor` to maintain the `vendor/` folder for older 1.7 and later runtimes.
//
// If either runtime has an issue, please create an Issue and I will address.
//
// Extensibility
//
// For version 1.x, you are not restricted in having full control over your feeds.
// You may choose to skip the API methods and instead use the structs directly. The
// fields have been grouped by RSS 2.0 and iTunes fields with iTunes specific fields
// all prefixed with the letter `I`.
//
// However, do note that the 2.x version currently in progress will break this
// extensibility and enforce API methods going forward. This is to ensure that the feed
// can both be marshalled, and unmarshalled back and forth (current 1.x branch can only
// be unmarshalled - hence the work for 2.x).
//
// Fuzzing Inputs
//
// `go-fuzz` has been added in 1.4.1, covering all exported API methods. They have been
// ran extensively and no issues have come out of them yet (most tests were ran overnight,
// over about 11 hours with zero crashes).
//
// If you wish to help fuzz the inputs, with Go 1.13 or later you can run `go-fuzz` on any
// of the inputs.
//
// go get -u github.com/dvyukov/go-fuzz/go-fuzz
// go get -u github.com/dvyukov/go-fuzz/go-fuzz-build
// go get -u github.com/eduncan911/podcast
// cd $GOPATH/src/github.com/eduncan911/podcast
// go-fuzz-build
// go-fuzz -func FuzzPodcastAddItem
//
// To obtain a list of available funcs to pass, just run `go-fuzz` without any parameters:
//
// $ go-fuzz
// 2020/02/13 07:27:32 -func flag not provided, but multiple fuzz functions available:
// FuzzItemAddDuration, FuzzItemAddEnclosure, FuzzItemAddImage, FuzzItemAddPubDate,
// FuzzItemAddSummary, FuzzPodcastAddAtomLink, FuzzPodcastAddAuthor, FuzzPodcastAddCategory,
// FuzzPodcastAddImage, FuzzPodcastAddItem, FuzzPodcastAddLastBuildDate, FuzzPodcastAddPubDate,
// FuzzPodcastAddSubTitle, FuzzPodcastAddSummary, FuzzPodcastBytes, FuzzPodcastEncode,
// FuzzPodcastNew
//
// If you do find an issue, please raise an issue immediately and I will quickly address.
//
// Roadmap
//
// The 1.x branch is now mostly in maintenance mode, open to PRs. This means no
// more planned features on the 1.x feature branch is expected. With the success of 6
// iTunes-accepted podcasts I have published with this library, and with the feedback from
// the community, the 1.x releases are now considered stable.
//
// The 2.x branch's primary focus is to allow for bi-direction marshalling both ways.
// Currently, the 1.x branch only allows unmarshalling to a serial feed. An attempt to marshall
// a serialized feed back into a Podcast form will error or not work correctly. Note that while
// the 2.x branch is targeted to remain backwards compatible, it is true if using the public
// API funcs to set parameters only. Several of the underlying public fields are being removed
// in order to accommodate the marshalling of serialized data. Therefore, a version 2.x is denoted
// for this release.
//
// Versioning
//
// We use SemVer versioning schema. You can rest assured that pulling 1.x branches will
// remain backwards compatible now and into the future.
//
// However, the new 2.x branch, while keeping the same API, is expected break those that
// bypass the API methods and use the underlying public properties instead.
//
// Release Notes
//
// v1.4.2
// * Slim down Go Modules for consumers (#32)
//
// v1.4.1
// * Implement fuzz logic testing of exported funcs (#31)
// * Upgrade CICD Pipeline Tooling (#31)
// * Update documentation for 1.x and 2.3 (#31)
// * Allow godoc2ghmd to run without network (#31)
//
// v1.4.0
// * Add Go Modules, Update vendor folder (#26, #25)
// * Add C.I. GitHub Actions (#25)
// * Add additional error checks found by linters (#25)
// * Go Fmt enclosure_test.go (#25)
//
// v1.3.2
// * Correct count len of UTF8 strings (#9)
// * Implement duration parser (#8)
// * Fix Github and GoDocs Markdown (#14)
// * Move podcast.go Private Methods to Respected Files (#12)
// * Allow providing GUID on Podcast (#15)
//
// v1.3.1
// * increased itunes compliance after feedback from Apple:
// - specified what categories should be set with AddCategory().
// - enforced title and link as part of Image.
// * added Podcast.AddAtomLink() for more broad compliance to readers.
//
// v1.3.0
// * fixes Item.Duration being set incorrectly.
// * changed Item.AddEnclosure() parameter definition (Bytes not Seconds!).
// * added Item.AddDuration formatting and override.
// * added more documentation surrounding Item.Enclosure{}
//
// v1.2.1
// * added Podcast.AddSubTitle() and truncating to 64 chars.
// * added a number of Guards to protect against empty fields.
//
// v1.2.0
// * added Podcast.AddPubDate() and Podcast.AddLastBuildDate() overrides.
// * added Item.AddImage() to mask some cumbersome addition of IImage.
// * added Item.AddPubDate to simply datetime setters.
// * added more examples (mostly around Item struct).
// * tweaked some documentation.
//
// v1.1.0
// * Enabling CDATA in ISummary fields for Podcast and Channel.
//
// v1.0.0
// * Initial release.
// * Full documentation, full examples and complete code coverage.
//
// References
//
// RSS 2.0: https://cyber.harvard.edu/rss/rss.html
//
// Podcasts: https://help.apple.com/itc/podcasts_connect/#/itca5b22233
//
package podcast