----- Original Message -----
> From: "nicolas mailhot" <nicolas.mail...@laposte.net>
> To: "Development discussions related to Fedora"
> <devel@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@lists.fedoraproject.org
> To unsubscribe send an email to devel-le...@lists.fedoraproject.org
>
_______________________________________________
devel mailing list -- devel@lists.fedoraproject.org
To unsubscribe send an email to devel-le...@lists.fedoraproject.org
