Nix / NixOS

To answer your question: no guideline (as is typical with nix).

I always check https://search.nixos.org/options first. There's a chance it's a package which requires setup or even a service that has extra config. If it's not there, then https://search.nixos.org/packages is next.

When multiple come up, it depends which prefix or suffix they have. Prefixes like pythonPackages. either mean the package is written in a specific programming language with its own packaging intricacies and its easier to keep them under that prefix, other prefixes like neovimPackages. mean it's a package for a program and something like a plugin or so. Probably more prefixes exist.

There are some agreed upon but badly documented suffixes (the usual nix style). But if it's a version suffix, then it's up to you to decide which one to use. In a comment you mentioned julia, well that's a programming language so you have to choose the version you want. Sometimes the manual has information on how to use the programming language or one of the wikis.

Anti Commercial-AI license

I lookup for the package here https://search.nixos.org/packages? I can find multiple versions.

It'd help if you mentioned the package itself.

two that sound right, two sound like rubbish and one is a plugin for something. How do I decide which of the two good sounding packages I should choose

Let's say you wanted to install neovim, there are many similar packages available, viz. neovim, neovim-gtk, neovim-qt, etc. they all have description and most packages have link to homepage, hinting their purpose. But you can ignore *-unwrapped packages if you are not packaging yourself.

What if the package or even both not work?

This seems like packaging problem, most of the time it works. If not, notifying the maintainers via issues could help or you'll have to fix it for yourself or use other package manager.

How do I know that it is up to date?

Go to package homepage if available and check their releases and compare them with version shown on search.nixos.org. If homepage is not available, go to source and get the url from src attribute and check the original source and compare with version shown on search.nixos.org.

How do I know that it will be updated in a timely manner? Can I update it?

You can check the commit history for the "source" file. Also you can update it yourself. If you're lucky and know nix, then you'll only have to update the url/version and hash like here.

is there a guideline for using nix packages?

you can checkout https://nixos.wiki/wiki/Nix_command and may be https://nix.dev/manual/nix/2.18/. Unfortunately I can't find an comprehensive guideline for begineers. Others can chime in if they know.

Notice about experimental features nix-command and flakes.

If you see documentations other official sources, most often they'll use flakes/nix-command but since they're not officially stabilised (not as in broken) yet, documentation/blogs may vary. This can be quite frustrating if you don't know about it.

Without flakes/nix-command, to install (let's say) neovim on non-NixOS distro nix-env -iA nixos.neovim, you can see that when search on search.nixos.org and click on the required packages, then choose one of the three tabs: nix-env, nix-shell or NixOS-configuration.

nix-env installs the packages in your user environment, you can rollback and stuff.

nix-shell downloads the package and spawns a new shell (your shell prompt changes to [nix-shell]:) and you can use the package there and package won't be installed. This is good for trying packages before installing.

For using flakes/nix-command, first you'll have to enable them otherwise you'll get this error

$ nix shell nixpkgs#neovim
error: experimental Nix feature 'nix-command' is disabled; use '--extra-experimental-features nix-command' to override

you can append --extra-experimental-features nix-command to the above command nix shell nixpkgs#neovim --extra-experimental-features nix-command and it'll work temporarily.

OR

Append this line experimental-features = nix-command flakes to /etc/nix/nix.conf to enable nix-command and flakes.

nix shell nixpkgs#neovim is equivalent to nix-shell -p neovim though in the former it's using nixpkgs-unstable branch of github.com/nixos/nixpkgs. nix profile install nixpkgs#neovim is equivalent to nix-env -iA nixos.neovim though it's said to stop using nix-env

PS: This could be more comprehensive, my writing skills are shit lol