update base README

CONTRIBUTING.md

@@ -4,12 +4,6 @@ Contributing to c-ares
 To contribute patches to c-ares, please generate a GitHub pull request
 and follow these guidelines:
 
- - Check that the Travis builds are green for your pull request.
+ - Check that the CI/CD builds are green for your pull request.
  - Please update the test suite to add a test case for any new functionality.
- - Build the library with `./configure --enable-debug --enable-maintainer-mode` and
+ - Build the library on your own machine and ensure there are no new warnings.
-   ensure there are no new warnings.
-
-To improve the chances of the c-ares maintainers responding to your request:
-
- - Also send an email to the mailing list at `c-ares@lists.haxx.se` describing your change.
- - To follow any associated discussion, please subscribe to the [mailing list](http://lists.haxx.se/listinfo/c-ares).

DEVELOPER-NOTES.md

@@ -0,0 +1,47 @@
+Developer Notes
+===============
+
+* The distributed `ares_build.h` in the official release tarballs is only
+  intended to be used on systems which can also not run the also distributed
+  `configure` or `CMake` scripts.  It is generated as a copy of
+  `ares_build.h.dist` as can be seen in the code repository.
+
+* If you check out from git on a non-`configure` or `CMake` platform, you must run
+  the appropriate `buildconf*` script to set up `ares_build.h` and other local
+  files before being able to compile the library.  There are pre-made makefiles
+  for a subset of such systems such as Watcom, NMake, and MinGW Makefiles. 
+
+* On systems capable of running the `configure` or `CMake` scripts, the process
+  will overwrite the distributed `ares_build.h` file with one that is suitable
+  and specific to the library being configured and built, this new file is
+  generated from the `ares_build.h.in` and `ares_build.h.cmake` template files.
+
+* If you intend to distribute an already compiled c-ares library you **MUST**
+  also distribute along with it the generated `ares_build.h` which has been
+  used to compile it. Otherwise, the library will be of no use for the users of
+  the library that you have built. It is **your** responsibility to provide this
+  file. No one at the c-ares project can know how you have built the library.
+  The generated file includes platform and configuration dependent info,
+  and must not be modified by anyone.
+
+* We support both the AutoTools `configure` based build system as well as the
+  `CMake` build system.  Any new code changes must work with both.
+
+* The files that get compiled and are present in the distribution are referenced
+  in the `Makefile.inc` in the current directory.  This file gets included in
+  every build system supported by c-ares so that the list of files doesn't need
+  to be maintained per build system.  Don't forget to reference new header files
+  otherwise they won't be included in the official release tarballs.
+
+* We cannot assume anything else but very basic C89 compiler features being
+  present. The lone exception is the requirement for 64bit integers which is
+  not a requirement for C89 compilers to support. Please do not use any extended
+  features released by later standards.
+
+* Newlines must remain unix-style for older compilers' sake.
+
+* Comments must be written in the old-style `/* unnested C-fashion */`
+
+* Try to keep line lengths below 80 columns and formatted as the existing code.
+  There is a `.clang-format` in the repository that can be used to run the
+  automated code formatter as such: `clang-format -i */*.c */*.h */*/*.c */*/*.h`

Makefile.am

@@ -30,7 +30,7 @@ EXTRA_DIST = AUTHORS CHANGES README.cares $(man_MANS) RELEASE-NOTES.md	\
  c-ares-config.cmake.in libcares.pc.cmake libcares.pc.in buildconf get_ver.awk \
  maketgz TODO README.msvc $(MSVCFILES) INSTALL.md README.md LICENSE.md \
  CMakeLists.txt Makefile.dj Makefile.m32 Makefile.netware Makefile.msvc \
- Makefile.Watcom AUTHORS CONTRIBUTING.md SECURITY.md TODO \
+ Makefile.Watcom AUTHORS CONTRIBUTING.md SECURITY.md DEVELOPER-NOTES.md TODO \
  cmake/EnableWarnings.cmake
 
 CLEANFILES = $(PDFPAGES) $(HTMLPAGES)

README.md

@@ -8,58 +8,62 @@
 [![Bugs](https://sonarcloud.io/api/project_badges/measure?project=c-ares_c-ares&metric=bugs)](https://sonarcloud.io/summary/new_code?id=c-ares_c-ares)
 [![Coverity Scan Status](https://scan.coverity.com/projects/c-ares/badge.svg)](https://scan.coverity.com/projects/c-ares)
 
-This is c-ares, an asynchronous resolver library.  It is intended for
+## Overview
+[c-ares](https://c-ares.org) is a modern DNS (stub) resolver library, written in
+C. It provides interfaces for asynchronous queries while trying to abstract the
+intricacies of the underlying DNS protocol.  It was originally intended for
 applications which need to perform DNS queries without blocking, or need to
-perform multiple DNS queries in parallel.  The primary examples of such
+perform multiple DNS queries in parallel.
-applications are servers which communicate with multiple clients and programs
-with graphical user interfaces.
 
-The full source code is available in the ['c-ares' release archives](https://c-ares.org/download/),
+One of the goals of c-ares is to be a better DNS resolver than is provided by
-and in a git repository: https://github.com/c-ares/c-ares.  See the
+your system, regardless of which system you use.  We recommend using
-[INSTALL.md](INSTALL.md) file for build information.
+the c-ares library in all network applications even if the initial goal of
+asynchronous resolution is not necessary to your application.
 
-If you find bugs, correct flaws, have questions or have comments in general in
+c-ares will build with any C89 compiler, is [MIT licensed](LICENSE.md),
-regard to c-ares (or by all means the original ares too), get in touch with us
+which makes it suitable for both free and commercial software. c-ares runs on
-on the c-ares mailing list: https://lists.haxx.se/listinfo/c-ares
+Linux, FreeBSD, OpenBSD, MacOS, Solaris, AIX, Windows, Android, iOS and many
+more operating systems.
 
-c-ares is distributed under the MIT license.
+c-ares has a strong focus on security, implementing safe parsers and data
+builders used throughout the code, thus avoiding many of the common pitfalls
+of other C libraries.  Through automated testing with our extensive testing
+framework, c-ares is constantly validated with a range of static and dynamic
+analyzers, as well as being constantly fuzzed by [OSS Fuzz](https://github.com/google/oss-fuzz).
 
-You'll find all c-ares details and news here:
+While c-ares has been around for over 20 years, it has been actively maintained
-        https://c-ares.org/
+both in regards to the latest DNS RFCs as well as updated to follow the latest
+best practices in regards to C coding standards.
 
+This is c-ares, an asynchronous resolver library.  It is intended for
+applications which need to perform DNS queries without blocking, or need to
+perform multiple DNS queries in parallel.  The primary examples of such
+applications are servers which communicate with multiple clients and programs
+with graphical user interfaces.
 
-## Notes for c-ares hackers
+## Code
 
-* The distributed `ares_build.h` file is only intended to be used on systems
+The full source code and revision history is available in our
-  which can not run the also distributed configure script.
+[GitHub  repository](https://github.com/c-ares/c-ares).  Our signed releases
+are available in the ['c-ares' release archives](https://c-ares.org/download/).
 
-* The distributed `ares_build.h` file is generated as a copy of `ares_build.h.dist`
-  when the c-ares source code distribution archive file is originally created.
 
-* If you check out from git on a non-configure platform, you must run the
+See the [INSTALL.md](INSTALL.md) file for build information.
-  appropriate `buildconf*` script to set up `ares_build.h` and other local files
-  before being able to compile the library.
 
-* On systems capable of running the `configure` script, the `configure` process
+## Communication
-  will overwrite the distributed `ares_build.h` file with one that is suitable
-  and specific to the library being configured and built, this new file is
-  generated from the `ares_build.h.in` template file.
 
-* If you intend to distribute an already compiled c-ares library you **MUST**
+**Issues** and **Feature Requests** should be reported to our
-  also distribute along with it the generated `ares_build.h` which has been
+[GitHub Issues](https://github.com/c-ares/c-ares/issues) page.
-  used to compile it. Otherwise, the library will be of no use for the users of
-  the library that you have built. It is **your** responsibility to provide this
-  file. No one at the c-ares project can know how you have built the library.
 
-* File `ares_build.h` includes platform and configuration dependent info,
+**Discussions** around c-ares and its use, are held on
-  and must not be modified by anyone. Configure script generates it for you.
+[GitHub Discussions](https://github.com/c-ares/c-ares/discussions/categories/q-a)
+or the [Mailing List](https://lists.haxx.se/mailman/listinfo/c-ares).  Mailing
+List archive [here](https://lists.haxx.se/pipermail/c-ares/).
+Please, do not mail volunteers privately about c-ares.
 
-* We cannot assume anything else but very basic compiler features being
+**Security vulnerabilities** are treated according to our
-  present. While c-ares requires an ANSI C compiler to build, some of the
+[Security Procedure](SECURITY.md), please email c-ares-security at
-  earlier ANSI compilers clearly can't deal with some preprocessor operators.
+ haxx.se if you suspect one.
 
-* Newlines must remain unix-style for older compilers' sake.
 
-* Comments must be written in the old-style /* unnested C-fashion */
 
-* Try to keep line lengths below 80 columns.