duncanlock.net

How to Contribute a Change to Nginx

Two screenshots of the nginx Welcome page
Figure 1. The nginx “Welcome” page, before & after my intended change.

I wanted to add dark mode support to the default nginx “Welcome to nginx” page. This is about the simplest change I could choose to make - it’s a simple, backwards compatible, small additive change to one single index.html file. My initial version of this change looks like this, and is added to the files <style> element, in the <head> section:

@media (prefers-color-scheme: dark) {
  body {
    background-color: #363839;
    color: #d1cec9;
  }
  a {
    color: #c4c4ff;
  }
}

So, this is the process of getting that change from my brain, into the upstream nginx codebase. 

Checking out the Code & Making the Change

The nginx project uses Mercurial, rather than git for source code control. So you will need Mercurial installed for this. This page has download links & installation info. If you are using Debian/Ubuntu, you can just run this to install it:

$ sudo apt install mercurial
// Once that's done, check to make sure
$ hg --version
Mercurial Distributed SCM (version 5.3.1)
...

Once Mercurial is installed, you can check out the source and make the change like this:

// Go to the folder where you want to check out the nginx source
$ cd ~/dev
// Use Mercurial to clone the nginx repo
$ hg clone http://hg.nginx.org/nginx
// Go into the folder
$ cd nginx
// Find the file you need to edit
$ grep -r 'Welcome' .
./docs/html/index.html:<title>Welcome to nginx!</title>
./docs/html/index.html:<h1>Welcome to nginx!</h1>
// Make the change
$ $EDITOR ./docs/html/index.html

To test this change, you can just open the ~/dev/nginx/docs/html/index.html in a browser using “File → Open”, as it’s just static HTML.

Contributing the Change Upstream

Nginx development is mailing list based, rather than Github/lab/forge/etc…​ based. The basic plan is to:

  1. Join the mailing list
  2. Send an email to the list, containing a patch with the change.

Follow the instructions here to join the mailing list. You will receive a confirmation email. Once you’ve done that, you can send an email to the list with your change in.

To get your change in a format that’s ready to email, I did this:

// Commit the change and write a changelog
$ hg commit
// Export the change as a patch, ready to email
$ hg export tip

This is the output of that, which I copied & pasted into an email – and sent it to nginx-devel@nginx.org:

# HG changeset patch
# User Duncan Lock <duncan.lock@gmail.com>
# Date 1628952253 25200
#      Sat Aug 14 07:44:13 2021 -0700
# Node ID 81294b370e774c792210904f710abc0a494c5c05
# Parent  dda421871bc213dd2eb3da0015d6228839323583
Add support for dark color scheme in default index.html page

Add a little CSS to index.html to support dark color schemes.
This will display the index page in dark colors if the user has
requested a dark color scheme in their system UI or browser, and
display the same as the previous version if not.

See: https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme

diff -r dda421871bc2 -r 81294b370e77 docs/html/index.html
--- a/docs/html/index.html      Tue Aug 10 23:43:17 2021 +0300
+++ b/docs/html/index.html      Sat Aug 14 07:44:13 2021 -0700
@@ -8,6 +8,15 @@
         margin: 0 auto;
         font-family: Tahoma, Verdana, Arial, sans-serif;
     }
+    @media (prefers-color-scheme: dark) {
+               body {
+                       background-color: #363839;
+                       color: #d1cec9;
+               }
+               a {
+                       color: #c4c4ff;
+               }
+    }
 </style>
 </head>
 <body>

Back & Forth on the Mailing List

This is my thread on the mailing lists web archive, showing the back & forth discussion which ensued after my initial email.

First Maxim Dounin, one of the nginx core developers, politely said no thanks:

Thank you for the patch. I don’t think this is something we want to customize in the example pages such as index.html, especially given that we don’t set other colors.

Maxim Dounin, https://mailman.nginx.org/pipermail/nginx-devel/2021-August/014218.html

My heart sank…​ but after a while I came back and read it again…​ “especially given that we don’t set other colors.”. I guess I shouldn’t have hardcoded those dark colors in my change – that’s fair enough. I then started looking to see if there was a way to tell the browser to just use its own built-in stylesheet for the dark-mode colors, just like it does for the regular, light-mode version.

A little while later, Steffan Weber replied with the answer:

You could add the following line which makes modern browsers use colors from their built-in dark color scheme:

<meta name=”color-scheme” content=”light dark”>

https://web.dev/color-scheme/

Steffan Weber, https://mailman.nginx.org/pipermail/nginx-devel/2021-August/014220.html

So, I said I’d submit a new updated patch in the morning.

Second Try

So, next morning I did some research & testing, then reset my repository to have another go:

$ hg strip tip

I then sent in this patch, with Steffan’s suggested change, which did exactly what we wanted:

# HG changeset patch
# User Duncan Lock <duncan.lock@gmail.com>
# Date 1629049097 25200
#      Sun Aug 15 10:38:17 2021 -0700
# Node ID 945d9836012ed84dea05577027a30a38e38a59f3
# Parent  dda421871bc213dd2eb3da0015d6228839323583
Add support for dark color scheme in default index & 50x pages

Add a meta tag to index.html & 50x.html to support dark color schemes.
This will display the index page in dark colors if the user has
requested a dark color scheme in their system UI or browser, and
display the same as the previous version if not.

This uses the browsers built-in styles and doesn't hard code any colors or styles.

diff -r dda421871bc2 -r 945d9836012e docs/html/50x.html
--- a/docs/html/50x.html        Tue Aug 10 23:43:17 2021 +0300
+++ b/docs/html/50x.html        Sun Aug 15 10:38:17 2021 -0700
@@ -2,6 +2,7 @@
 <html>
 <head>
 <title>Error</title>
+<meta name="color-scheme" content="light dark">
 <style>
     body {
         width: 35em;
diff -r dda421871bc2 -r 945d9836012e docs/html/index.html
--- a/docs/html/index.html      Tue Aug 10 23:43:17 2021 +0300
+++ b/docs/html/index.html      Sun Aug 15 10:38:17 2021 -0700
@@ -2,6 +2,7 @@
 <html>
 <head>
 <title>Welcome to nginx!</title>
+<meta name="color-scheme" content="light dark">
 <style>
     body {
         width: 35em;

Then Maxim replied saying, essentially, “better, but I’d rather use CSS instead of adding a meta tag” - i.e. remove the meta tag and add this CSS: html { color-scheme: light dark; }.

Maxim also included his patch which implemented this and asked me to test it.

I tested his patch, which worked great and then made a suggestion about removing the hardcoded fonts too, which was declined, sadly.

Done & Released

Maxim then committed his final version of the patch…​ and that was it!

So, in the end, I didn’t actually get any of my code into nginx, but the process was fairly painless, everyone was polite and helpful – and the nginx welcome & error pages now respect your dark mode preferences. I did at least get my name in the changelog:

Dark mode support in welcome and 50x error pages.

Prodded by Duncan Lock.

This is what the welcome page code looks like now:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
<style>
html { color-scheme: light dark; }
body { width: 35em; margin: 0 auto;
font-family: Tahoma, Verdana, Arial, sans-serif; }
</style>
</head>
<body>
<h1>Welcome to nginx!</h1>
<p>If you see this page, the nginx web server is successfully installed and
working. Further configuration is required.</p>

<p>For online documentation and support please refer to
<a href="http://nginx.org/">nginx.org</a>.<br/>
Commercial support is available at
<a href="http://nginx.com/">nginx.com</a>.</p>

<p><em>Thank you for using nginx.</em></p>
</body>
</html>

This got released on Aug 31st 2021, as part of nginx 1.21.2 🎉


Related Posts


Comments