----- Original Message -----
From: "nicolas mailhot"
<nicolas.mailhot(a)laposte.net>
To: "Development discussions related to Fedora"
<devel(a)lists.fedoraproject.org>
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(a)lists.fedoraproject.org
> To unsubscribe send an email to devel-leave(a)lists.fedoraproject.org
>