----- 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 – 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) – 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. — 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 — 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 _______________________________________________ devel mailing list -- devel@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe send an email to devel-leave@xxxxxxxxxxxxxxxxxxxxxxx
