Added new primary README.md file. #165

mtbChef · 2024-09-11T22:06:46Z

Proposed changes

New primary README file for the project

mtbChef · 2024-09-12T17:44:26Z

Helpful, but why touch makefile

To follow the .md extension standard

pkgzx

Very good

pluknet

Style: too long lines should be rewrapped (whenever allowed by markdown) for maintenance reasons.

Lines are typically no longer than 70 characters, with an absolute maximum of 80 characters.
Each new sentence begins on a new line.
If you're experiencing difficulties with the style, please see how it is done in CONTRIBUTING.md.

lcrilly · 2024-09-13T10:17:31Z

Markdown requires special treatment IMHO, and should not be treated like source code or true markup languages.

Primarily it needs to read well using GitHub's web view, but also be readable as plain text and with with other Markdown readers.

Linebreaks are semantically significant when viewed in a terminal, so rules like 'new sentence on a new line' actively hurts readability for prose paragraphs.

Linebreaks in lists have different behavior between renderers.

pluknet · 2024-09-13T09:59:39Z

README.md

+  <img alt="NGINX Banner">
+</picture>
+
+NGINX (pronounced "engine x" or "en-jin-eks") is the world's most popular Web Server, high performance Load Balancer, Reverse Proxy, API Gateway and Content Cache.


Where did you get "en-jin-eks" from? This pronunciation is not documented anywhere, google search gives zero matches:

"en-jin-eks" site:nginx.org

"en-jin-eks" site:nginx.com

"en-jin-eks" site:f5.com

Please use official terms as taken from https://nginx.org/en/
nginx ("engine x") is ...

pluknet · 2024-09-13T10:04:03Z

README.md

+  <img alt="NGINX Banner">
+</picture>
+
+NGINX (pronounced "engine x" or "en-jin-eks") is the world's most popular Web Server, high performance Load Balancer, Reverse Proxy, API Gateway and Content Cache.


nginx opensource doesn't use capitalization, it is written literally as "nginx".
"NGINX" is some term reserved for other purposes.
Again, please see https://nginx.org/en/ for the proper usage.

pluknet · 2024-09-13T10:08:55Z

README.md

+
+NGINX (pronounced "engine x" or "en-jin-eks") is the world's most popular Web Server, high performance Load Balancer, Reverse Proxy, API Gateway and Content Cache.
+
+NGINX is free and open source software, distributed under the terms of a simplified [2-clause BSD-like license](LICENSE).


Again, this differs from the official documentation without a reason:
https://nginx.org/en/

pluknet · 2024-09-13T10:14:27Z

README.md

+
+NGINX is free and open source software, distributed under the terms of a simplified [2-clause BSD-like license](LICENSE).
+
+Enterprise distributions, commercial support and training are available from [F5, Inc](https://www.f5.com/products/nginx).


The purpose of the README file is to provide intro how to use software.
Advertising doesn't belong here.

Please see how this is done properly in side repos:
https://github.com/nginx/njs/
https://github.com/nginx/nginx-tests/
https://github.com/nginx/nginx.org/

pluknet · 2024-09-13T10:41:52Z

README.md

+Enterprise distributions, commercial support and training are available from [F5, Inc](https://www.f5.com/products/nginx).
+
+> [!IMPORTANT]
+> The goal of this README is to provide a basic, structured introduction to NGINX for novice users. Please refer to the [full NGINX documentation](https://nginx.org/en/docs/) for detailed information on [installing](https://nginx.org/en/docs/install.html), [building](https://nginx.org/en/docs/configure.html), [configuring](https://nginx.org/en/docs/dirindex.html), [debugging](https://nginx.org/en/docs/debugging_log.html), and more. These documentation pages also contain a more detailed [Beginners Guide](https://nginx.org/en/docs/beginners_guide.html), How-Tos, [Development guide](https://nginx.org/en/docs/dev/development_guide.html), and a complete module and [directive reference](https://nginx.org/en/docs/dirindex.html).


This can be replaced with a single link to nginx documentation that provides all these links:
Installing nginx
Building nginx from Sources
Beginner’s Guide
Development guide

Further, it provides links to many other documents.
It is not clear about the choice why you provided the given subset of links.

That said, this paragraph looks like a content duplication, just in another wording.
The downside of this is it can quickly became out of date due to excessive details, making it necessary to update the file in the source code rather often than never, which I'd like to avoid if possible.

configuring

This is not about configuring, this is an alphabetical index of directives.
Also, you mention the directive index two times, but omit the index of variables.

pluknet · 2024-09-13T13:25:42Z

README.md

+To run the installed binary, issue the following command:
+
+```bash
+sudo /usr/local/nginx/sbin/nginx


sudo is not necessarily required, it depends on configuration

To make README generic, it's better to avoid mentioning sudo, which may not be available or some other mechanism might be used ("su", "doas", etc) to get privileges.

Good point, kind of a chaos

Needed when using default location

pluknet · 2024-09-13T13:33:38Z

README.md

+sudo /usr/local/nginx/sbin/nginx
+```
+
+You may test NGINX operation using `curl`.


We have a separate nginx test suite you may want to mention.

Also, it is quite vague what the purpose of this curl example is.
Given the "/usr/local/nginx/sbin/nginx" path for the binary mentioned above, this is about building from opensource. I believe that such experienced users understand what to do next.
For the record, our binary packages use a different prefix: "/usr/sbin/nginx"

More appropriate for nginx.org

pluknet · 2024-09-13T13:39:27Z

README.md

+
+# Additional help and resources
+- See the [NGINX Community Blog](https://blog.nginx.org/) for more tips, tricks and HOW-TOs related to NGINX and related projects.
+- Access [nginx.org](https://nginx.org/), your go-to source for all documentation, information and software related to the NGINX suite of projects.


Actually, nginx.org is the primary resource, not some additional one.
As a proof, you can see this link on the repo page: https://github.com/nginx/nginx

pluknet · 2024-09-13T13:41:47Z

README.md

+[2-clause BSD-like license](LICENSE)
+
+---
+Additional documentation available at: https://nginx.org/en/docs


There is already the section "Additional help and resources", no need to repeat twice.

pluknet · 2024-09-13T13:44:25Z

README.md

+See our [changelog](https://nginx.org/en/CHANGES) to keep track of updates.
+
+# License
+[2-clause BSD-like license](LICENSE)


This duplicates the license text above.

Also, if the primary audience is GitHub users, the LICENSE plate already exists in the GitHub interface, and a separate LICENSE file exists in the root directory.

This comment was marked as resolved.

Sign in to view

mtbChef force-pushed the update-readme branch from effe4cb to fcb8080 Compare September 12, 2024 17:39

mtbChef changed the title ~~New README~~ Added new primary README.md file. Sep 12, 2024

pkgzx approved these changes Sep 12, 2024

View reviewed changes

ninaforsyth approved these changes Sep 12, 2024

View reviewed changes

This comment was marked as resolved.

Sign in to view

pluknet requested changes Sep 13, 2024

View reviewed changes

mtbChef force-pushed the update-readme branch from b32d9b5 to a1584fb Compare September 19, 2024 23:36

Added new primary README.md file.

5b63b10

Maryna-f5 force-pushed the update-readme branch from a1584fb to 5b63b10 Compare September 20, 2024 13:52

ninaforsyth merged commit b1e0740 into nginx:master Sep 20, 2024
1 check passed

route443 mentioned this pull request Oct 1, 2024

Update index.html to reflect updated links and add F5 to the name. #231

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added new primary README.md file. #165

Added new primary README.md file. #165

mtbChef commented Sep 11, 2024 •

edited

Loading

This comment was marked as resolved.

mtbChef commented Sep 12, 2024

pkgzx left a comment

This comment was marked as resolved.

pluknet left a comment

lcrilly commented Sep 13, 2024

pluknet Sep 13, 2024

pluknet Sep 13, 2024

pluknet Sep 13, 2024

pluknet Sep 13, 2024

pluknet Sep 13, 2024

pluknet Sep 13, 2024

zzz6519003 Sep 14, 2024

mtbChef Sep 19, 2024

pluknet Sep 13, 2024

mtbChef Sep 19, 2024

pluknet Sep 13, 2024

pluknet Sep 13, 2024

pluknet Sep 13, 2024


		NGINX (pronounced "engine x" or "en-jin-eks") is the world's most popular Web Server, high performance Load Balancer, Reverse Proxy, API Gateway and Content Cache.

		NGINX is free and open source software, distributed under the terms of a simplified [2-clause BSD-like license](LICENSE).


		NGINX is free and open source software, distributed under the terms of a simplified [2-clause BSD-like license](LICENSE).

		Enterprise distributions, commercial support and training are available from [F5, Inc](https://www.f5.com/products/nginx).

Added new primary README.md file. #165

Added new primary README.md file. #165

Conversation

mtbChef commented Sep 11, 2024 • edited Loading

Proposed changes

This comment was marked as resolved.

mtbChef commented Sep 12, 2024

pkgzx left a comment

Choose a reason for hiding this comment

This comment was marked as resolved.

pluknet left a comment

Choose a reason for hiding this comment

lcrilly commented Sep 13, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mtbChef commented Sep 11, 2024 •

edited

Loading