----- Original Message ----- > From: "nicolas mailhot" <nicolas.mailhot@xxxxxxxxxxx> > To: "Development discussions related to Fedora" <devel@xxxxxxxxxxxxxxxxxxxxxxx> > Sent: Tuesday, January 23, 2018 7:45:06 PM > Subject: Re: <DKIM> Re: Proposed Fedora packaging guideline: More Go packaging > > > > ----- Mail original ----- > De: "Mátyás Selmeci" > > Hi, > > > This looks pretty cool! > > Thanks for the feedback! > > > One thing I notice in the limitations section of > > your draft is a lot of "we can't do XXX due to lack of release > > discipline..." > > > Do you have any recommendations for Go programmers on how to structure > > their software so that it is easy to package? > > If there is an interest I can add a section on how to make a Go project > easier to package, sure. > > It won't be earth-shattering, just the Go declination of basic common sense > rules that are needed in any coding language, that many Go projects already > apply (unfortunately not all of them): > > — do not change your import path every other month > — do not make your code accessible through multiple import paths > – only use smallcaps in your import path (I know some systems are case > insensitive. Many others are NOT) > – communicate clearly the canonical import path of the project at the top of > your README.md > — if you absolutely need to change your import path fix your code to use the > new import path do not rely on http redirections > – that includes testing and example code > — do not add a .git suffix to your import path > > — use _testdata for all the material needed by unit test - make sure that all tests and exclusive test dependencies are really only in _test.go files > – put your example code in _examples (with subdirectories if you ship several > examples). Do not use creative unusual names such as tutorial. > – do not pepper your subdirectories with .md files. Keep documentation in the > project root or in a docs root subdirectory if there is too much of it > — add a one-line summary and a least a § describing what your project does at > the top of your README.md > > — choose licenses already vetted by Fedora or Debian > https://fedoraproject.org/wiki/Licensing:Main?rd=Licensing#Good_Licenses > – add a licensing file named LICENSE > — use unmodified plaintext canonical licensing texts, that state the LICENSE > name at the top of the file > — if you absolutely want to add an extension to make Windows happy, use > LICENSE.txt > — if you absolutely want to name your licensing file something else, please > do not use something.md > — do not hide your licensing terms in README.md, do not refer to a license by > name without providing its text > > – do releases > — do releases, even for minor fixes. If you haven't felt the need to touch a > project for months its latest state should be released! > — do releases, even for projects that can only be called through another > project. Do not rely on this other project to set code state through > vendoring (that's easy to do, just propagate the tip project version to the > ancillary projects at release time, like kubernetes does) > – use semver for your releases https://semver.org/ Distributors and godep > will thank you > – if your project is in git, use a different branch for every major version > of your project > — if your project is in git, tag your release x.y.z as x.y.z, or vx.y.z, > never as vx.y.zprettybeta. Versions and version tags are not the right place > to document a project maturity. > — numbers are cheap, never reuse the same number for a pre-release and a > final release, increase the minor version! > – please version your import paths with each major release (gopkg.in is good > for that) - ideally do major releases in separate branches, so you can do minor fixes/releases easily even for older major releases(look at GC) - do release whenever you alter your API, extending it, modifying it, removing some and document it in the release notes > > – use releases of the projects you depend on > — never depend on a project that already depends on you (otherwise software > dependencies stop being a nice directed acyclic graph and you get into > dependency loop hell. That's a nasic software engineering golden rule, not > respecting it will bite you sooner or later with or without linux distros, > despite vendoring) > – if for some reason, one of the projects you depend on does not release, > please ask nicely it to do so > – if for some reason you need a code state in tip which is not in a release, > please inform the origin you'd like it to do a release, and switch to this > release as soon as it is available > – never depend on a commit state somewhere between two releases > — document the major versions of the stuff you depend on somewhere easy to > find. If a major version is only usable past as specific minor version, > document it > – add a unit test that detects if the project you depend on is missing the > part that requires being after this minor version > > – if your project provides wrappers, connexion glue or anything similar to > many many many other projects keep the code for each other project in a > separate subdirectory (Go package) so it can be desactivated without > impacting the rest of your code if the other project ode has a problem. > > — never add changes to the projects you reuse, submit the changes to those > projects > — if you absolutely need to change a project you reuse, fork it cleanly with > a new import path so distributors do not accidentally reinject the original > project > — don't forget to rebase your code on the original project if you don't have > the energy to maintain your own fork > – rebase to the latest minor version of every project you depend on at > release time. Do not let changes accumulate till rebasing becomes a major > endeavor. > - if you ever have to use vendor-ing, first don't use it, secondly if you really really have too - pull in the vendor-ed deps, fresh in your build infrastructure, don't pollute the repo with (mostly) outdated rotting code > — do not hide vendor subdirectories deep inside your project tree. Only use a > toplevel directory > – identify clearly all the bits scrounged from other projects and not located > in vendor in your README.md file > – if part of your project is generated code, document cleanly how to remove > what you already generated and how to regenerate it from scratch > > – put the code that needs to be built into a binary in cmd/binary-name > > – do not test projects that depend on you from your project. Contribute the > testing code to those projects (otherwise software dependencies stop being a > nice directed acyclic graph and you get into dependency loop hell) > – do not ship not-working testing code (people will thing their build is > broken) > — do not test that a project you depend on has a specific import path, it may > rename itself in the future > – do not ship tests that depend on special parameters, go test should always > just work - if you have some special needs in testing(networking, special HW,...), detect those, if not met skip(and log) > — do not ship tests that rely on being in a specific directory, as long as > the test code in in GOPATH it should be testable regardless of the location > — do not ship tests that depend on specific timings, distributor build farms > may be heavily loaded, causing the tests to fail. > – if a test depends on a special preparation, ship a shell script that > describes this preparation. Do not rely on Ubuntu docker images. > – if a test depends on network access, make it fail gracefully when this > access is blocked (with PASS not FAIL) > — never do go get from tests > — never stomp on GOPATH in tests > > Anyway, you get the idea. This is probably not exhaustive, it needs to be > maintained in a wiki page if people find it useful > > Regards, > > -- > Nicolas Mailhot > Very nice list, it would be nice to have it as sub-wiki page of guidelines. I have took liberty to add few points. JC > > _______________________________________________ > devel mailing list -- devel@xxxxxxxxxxxxxxxxxxxxxxx > To unsubscribe send an email to devel-leave@xxxxxxxxxxxxxxxxxxxxxxx > _______________________________________________ devel mailing list -- devel@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe send an email to devel-leave@xxxxxxxxxxxxxxxxxxxxxxx
