A README should take a buyer from the package they downloaded to a result they can check. Use the template in this guide to document your code's requirements, setup, configuration, and updates. Then follow it from a fresh copy of the package before you upload it.
Put README.md at the top level of your ZIP file, alongside the product files. Kurodyne also
accepts README.txt, but Markdown lets you format commands, headings, and lists. A README is
optional; when you include one, anyone can read it on the product page before buying.
Keep purchase-only links, keys, codes, and passwords out of the README. Put those details in the release's Private usage instructions or the Key value field. Describe required software, accounts, paid plans, credentials, and access limits in Public requirements too, so buyers can check them before purchase.
Before writing, gather the exact runtime versions you tested, the commands that work from your package, a small sample input, and its expected result. List any external services and costs the buyer needs to cover. Include a short example of what the code does that you are comfortable making public.
Copy this block into README.md. Replace every placeholder in square brackets, such as
[PRODUCT NAME], with your product's details, including the command blocks. The placeholders are
writing prompts, not commands to run. Remove sections that don't apply, or say that no configuration
or external account is needed.
For an app, include the database setup, build and start commands, and deployment instructions that your listing promises. For a command-line tool, include a sample input and output. For a plugin, include the installation step inside its host application and the host versions you tested.
This example describes a fictional product called Task Summary, a local command-line tool. Its source files aren't included in this article. The README shows the level of detail to write for your own package; replace its product facts and commands with ones you have tested.
The example uses Node.js's
--env-file option(opens in a new tab)
to load configuration explicitly.
A file named .env doesn't make an application read it by itself.
For each environment variable your code reads, explain where the buyer gets its value, whether it
is required, and whether it is secret. Ship .env.example with placeholders or harmless defaults.
Keep your working .env and real credentials out of the package. Document how the program loads the
file and when configuration changes take effect. If the product needs a paid service or the buyer's
own API account, put that requirement in the listing as well as the README.
Check dependencies and included fonts, icons, images, sample data, and copied code before filling
in the notices section. When the package includes third-party material, identify it in
THIRD_PARTY_NOTICES.md with its source, license, required notices, and buyer obligations. Include
the license texts and other files its terms require. A link to a project's home page doesn't take
the place of a required notice. The
listing standards and the
Commercial License third-party material section explain Kurodyne's
requirements.
You don't need a separate license file for your own code. The Kurodyne Commercial License governs that material, and a README can't add seller-specific restrictions to it. Keep third-party notices distinct from that license; each component's terms determine its obligations. Only state that no third-party material is bundled after checking the package.
Follow Third-Party Notices for Code You Sell for the inventory steps and a filled notices-file example.
Put the finished README.md alongside the readable source, example configuration, sample files,
and required notices in a package folder. Keep README.md and any THIRD_PARTY_NOTICES.md at the
ZIP file's top level.
Follow the packaging steps in Publish Your First Product to check the package requirements and build the ZIP file. A package containing only a top-level README and license or notice files can't be submitted for review.
Test the README against the exact files you intend to upload:
- Extract the final ZIP file into a new folder. Check that
README.mdis at the top level, not inside an extra enclosing folder. - Follow the setup using only the README, packaged files, and prerequisites you list. Use a clean environment for each platform you claim to support, without relying on your project's installed dependencies, saved credentials, or local configuration.
- Run the included sample and compare the result with the documented output. Then try the documented step for using the buyer's own input or customizing the product.
- Check every filename, command, configuration variable, and link. Search the README for any remaining placeholder in square brackets, replace it, and record recovery steps for failures you encounter.
- For an update, test upgrading from copies of earlier releases buyers may have kept to the package you plan to upload. Once approved, the update becomes the only release buyers can download from their Library, so don't require an intermediate release. See Updating a Product You Sell.
- Check that the README's requirements match the listing, and that every public example is safe to show before purchase.
If a command works only from your development folder, find the missing file, dependency, or setup step and add it before packaging again. If the expected result is hard to describe, choose a smaller sample that gives the buyer a clear way to confirm the setup worked.
Upload the package you tested in the Product Editor's Files section and check that the Package
checklist finds your README. If it doesn't, check the filename and rebuild the ZIP file from the
package folder's contents so README.md is at the top level. Test and upload the corrected package.
The README doesn't replace the release's required Private usage instructions. Keep those instructions current with the files buyers receive. Follow Publish Your First Product for the remaining listing steps, or start selling on Kurodyne if you haven't set up your store.