nixpkgs/doc
Dee Anzorge f124c73686 nginx: change etags for statically compressed files served from store
Per RFC 9110, [section 8.8.1][1], different representations of the same
resource should have different Etags:

> A strong validator is unique across all versions of all
> representations associated with a particular resource over time.
> However, there is no implication of uniqueness across representations
> of different resources (i.e., the same strong validator might be in
> use for representations of multiple resources at the same time and
> does not imply that those representations are equivalent)

When serving statically compressed files (ie, when there is an existing
corresponding .gz/.br/etc. file on disk), Nginx sends the Etag marked
as strong. These tags should be different for each compressed format
(as shown in  an explicit example in section [8.8.3.3][2] of the RFC).
Upstream Etags are composed of the file modification timestamp and
content length, and the latter generally changes between these
representations.

Previous implementation of Nix-specific Etags for things served from
store used the store hash. This is fine to share between different
files, but it becomes a problem for statically compressed versions of
the same file, as it means Nginx was serving different representations
of the same resource with the same Etag, marked as strong.

This patch addresses this by imitating the upstream Nginx behavior, and
appending the value of content length to the store hash.

[1]: https://www.rfc-editor.org/rfc/rfc9110.html#name-validator-fields
[2]:
https://www.rfc-editor.org/rfc/rfc9110.html#name-example-entity-tags-varying
2024-01-13 22:07:50 +01:00
..
build-helpers doc: update mkBinaryCache section with admonitions and conventions 2023-12-25 17:34:59 -08:00
contributing doc/vulnerability-roundup: Rough move to new contribution doc files 2023-08-13 22:04:56 +02:00
development CONTRIBUTING.md: Move opening issues section to Nixpkgs manual 2023-08-13 22:04:57 +02:00
doc-support doc: Render lib.fixedPoints 2023-07-08 18:46:08 +02:00
functions lib.fileset: Move introduction section above the functions 2023-11-19 15:00:57 +01:00
hooks Merge master into staging-next 2023-11-14 18:01:11 +00:00
languages-frameworks doc/python: update buildPythonApplication example 2024-01-01 23:39:38 +01:00
module-system lib.modules: configurationClass -> class 2023-05-06 18:32:59 +02:00
old doc: fix typos 2022-12-17 18:21:48 -05:00
packages nginx: change etags for statically compressed files served from store 2024-01-13 22:07:50 +01:00
stdenv Merge pull request #271797 from bzm3r/master 2023-12-21 17:14:30 +01:00
tests doc/tests/manpage-urls.py: Add type annotations 2023-12-18 20:38:17 +00:00
using treewide: fix redirected and broken URLs 2023-11-11 10:49:01 +01:00
build-helpers.md doc: add introduction to build helpers 2023-11-07 19:58:54 +00:00
common.nix nixpkgs manual: extract some build paths 2023-07-25 17:00:51 +07:00
contributing.md doc: render nixpkgs manual with nrd 2023-07-01 20:59:29 +02:00
default.nix doc: Add test for broken links in manpage-urls.json 2023-12-18 20:28:51 +00:00
development.md CONTRIBUTING.md: Move opening issues section to Nixpkgs manual 2023-08-13 22:04:57 +02:00
functions.md lib.fileset: Move introduction section above the functions 2023-11-19 15:00:57 +01:00
lib.md doc: render nixpkgs manual with nrd 2023-07-01 20:59:29 +02:00
manpage-urls.json doc/manpage-urls.json: Fix link to gnunet's manual 2023-12-18 20:28:51 +00:00
manual.md.in doc: Rename to Nixpkgs reference manual and state purpose 2023-12-08 01:26:31 +01:00
overrides.css
preface.chapter.md doc: Rename to Nixpkgs reference manual and state purpose 2023-12-08 01:26:31 +01:00
README.md Merge pull request #272183 from infinisil/nixpkgs-reference 2023-12-10 07:07:20 +01:00
shell.nix nixpkgs/NixOS manuals: devmode feature 2023-07-25 17:03:15 +07:00
stdenv.md doc: render nixpkgs manual with nrd 2023-07-01 20:59:29 +02:00
style.css
using-nixpkgs.md doc: minimal documentation of supported platforms 2023-10-02 21:21:56 +02:00

Contributing to the Nixpkgs reference manual

This directory houses the sources files for the Nixpkgs reference manual.

Going forward, it should only contain reference documentation. For tutorials, guides and explanations, contribute to https://nix.dev/ instead.

For documentation only relevant for contributors, use Markdown files and code comments in the source code.

Rendered documentation:

The rendering tool is nixos-render-docs, sometimes abbreviated nrd.

Contributing to this documentation

You can quickly check your edits with nix-build:

$ cd /path/to/nixpkgs
$ nix-build doc

If the build succeeds, the manual will be in ./result/share/doc/nixpkgs/manual.html.

devmode

The shell in the manual source directory makes available a command, devmode. It is a daemon, that:

  1. watches the manual's source for changes and when they occur — rebuilds
  2. HTTP serves the manual, injecting a script that triggers reload on changes
  3. opens the manual in the default browser

Syntax

As per RFC 0072, all new documentation content should be written in CommonMark Markdown dialect.

Additional syntax extensions are available, all of which can be used in NixOS option documentation. The following extensions are currently used:

Tables

Tables, using the GitHub-flavored Markdown syntax.

Anchors

Explicitly defined anchors on headings, to allow linking to sections. These should be always used, to ensure the anchors can be linked even when the heading text changes, and to prevent conflicts between automatically assigned identifiers.

It uses the widely compatible header attributes syntax:

## Syntax {#sec-contributing-markup}

Note

NixOS option documentation does not support headings in general.

Inline Anchors

Allow linking arbitrary place in the text (e.g. individual list items, sentences…).

They are defined using a hybrid of the link syntax with the attributes syntax known from headings, called bracketed spans:

- []{#ssec-gnome-hooks-glib} `glib` setup hook will populate `GSETTINGS_SCHEMAS_PATH` and then `wrapGAppsHook` will prepend it to `XDG_DATA_DIRS`.

If you omit a link text for a link pointing to a section, the text will be substituted automatically. For example [](#chap-contributing).

This syntax is taken from MyST.

Roles

If you want to link to a man page, you can use {manpage}`nix.conf(5)`. The references will turn into links when a mapping exists in doc/manpage-urls.json.

A few markups for other kinds of literals are also available:

  • {command}`rm -rfi`
  • {env}`XDG_DATA_DIRS`
  • {file}`/etc/passwd`
  • {option}`networking.useDHCP`
  • {var}`/etc/passwd`

These literal kinds are used mostly in NixOS option documentation.

This syntax is taken from MyST. Though, the feature originates from reStructuredText with slightly different syntax.

Admonitions

Set off from the text to bring attention to something.

It uses pandocs fenced divs syntax:

::: {.warning}
This is a warning
:::

The following are supported:

Definition lists

For defining a group of terms:

pear
:   green or yellow bulbous fruit

watermelon
:   green fruit with red flesh

Commit conventions

  • Make sure you read about the commit conventions common to Nixpkgs as a whole.

  • If creating a commit purely for documentation changes, format the commit message in the following way:

    doc: (documentation summary)
    
    (Motivation for change, relevant links, additional information.)
    

    Examples:

    • doc: update the kernel config documentation to use nix-shell

    • doc: add information about nix-update-script

      Closes #216321.

  • If the commit contains more than just documentation changes, follow the commit message format relevant for the rest of the changes.