Update docs to cover contributing.

diff --git a/README.md b/README.md
index d44f04aba1428a1678dda43747a5b532c1c005fa..46f6f1e7f06f92203ced0c84e2b99c72f887f247 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,16 +1,24 @@
 # mailpopbox
 
 # mailpopbox
 

-Mailpopbox is a single-user mail server, providing SMTP and POP facilities. It acts as a catch-all,
-wildcard email server for an entire domain name. Any message addressed to an account at the
-configured domain will be deposited into a single mailbox, which can then be accessed using the POP3
-protocol.
+Mailpopbox is a single-user mail server with SMTP and POP facilities. Its purpose is to provide
+privacy through anonymity by acting as a catch-all, wildcard email server for an entire domain name.
+Any message addressed to an account at the configured domain will be deposited into a single
+mailbox, which can then be accessed using the POP3 protocol.

 
 The usage scenario is to configure your primary email provider (e.g.,
 [Gmail](https://support.google.com/mail/answer/7104828)) or client to POP messages off the
 server. Any time you need to provide an email address, you can give out
 
 The usage scenario is to configure your primary email provider (e.g.,
 [Gmail](https://support.google.com/mail/answer/7104828)) or client to POP messages off the
 server. Any time you need to provide an email address, you can give out

-*\<arbitrary-string@domain.com\>*, allowing you to use site/service/person-specific email addresses.
+`arbitrary-string@domain.com`, allowing you to use site/service/person-specific email addresses.

 Mail is collected into a single maildrop that can be POP'd out into your normal mailbox.
 
 Mail is collected into a single maildrop that can be POP'd out into your normal mailbox.
 

+## Send-As SMTP
+
+Mailpopbox also provides a way to reply to messages from an arbitrary email address at the domain.
+Since mailpopbox is designed as a catch-all mail server, it would be impractical to administer SMTP
+accounts to enable replying from any address handled by the server. Instead, the SMTP authenticates
+a single *mailbox* user, and if the message's Subject header has a special `[sendas:ADDRESS]`
+string, the server will alter the From message header to be from ADDRESS@DOMAIN.
+

 ## Installation
 
 Installation requires a server capable of binding on port 25 for SMTP and 995 for POP3. A TLS
 ## Installation
 
 Installation requires a server capable of binding on port 25 for SMTP and 995 for POP3. A TLS


@@ -19,21 +27,24 @@ certificate is also required to have a secure connection for authenticating to t
 
 ## Building
 
 
 ## Building
 

-To build mailpopbox for a Linux server, you need [Go](https://golang.org) and git:
+Building mailpopbox only requires [Go](https://golang.org) and git. Clone the repository and type
+`go build`. Cross-compilation is supported since the server is written in pure Go.

 
 

-    $ git clone https://src.bluestatic.org/mailpopbox.git
-    $ cd mailpopbox
-    $ GOOS=linux GOARCH=amd64 go build
+## Contributing

 
 

-The `GOOS` and `GOARCH` environment variables are only needed when cross-compiling (e.g. on a Mac).
+[![CI](https://github.com/rsesek/mailpopbox/workflows/CI/badge.svg)](https://github.com/rsesek/mailpopbox/actions?query=workflow%3ACI)

 
 

-## Send-As SMTP
+The canonical home for the repository is on
+[src.bluestatic.org](https://src.bluestatic.org/?p=mailpopbox.git), but it is also hosted on
+[Github](https://github.com/rsesek/mailpopbox) to enable collaboration.

 
 

-Mailpopbox also provides a way to reply to messages from an arbitrary email address at the domain.
-Since mailpopbox is designed as a catch-all mail server, it would be impractical to administer SMTP
-accounts to enable replying from any address handled by the server. Instead, the SMTP authenticates
-a single *mailbox* user, and if the message's Subject header has a special `[sendas:ADDRESS]`
-string, the server will alter the From message header to be from ADDRESS@DOMAIN.
+Issues should be reported on the [Github issue tracker](https://github.com/rsesek/mailpopbox/issues).
+
+Contributions are welcome. Please:
+- Ensure tests pass and that new changes have adequate code coverage (`make coverage`)
+- Code is formatted with `go fmt`
+- Commit history is clean (one logical change per commit)
+- Commit message is well-formatted

 
 ## RFCs
 
 
 ## RFCs
 


@@ -45,5 +56,5 @@ This server implements (partially) the following RFCs:
 - [SMTP Service Extension for Secure SMTP over Transport Layer Security, RFC 3207](https://tools.ietf.org/html/rfc3207)
 - [SMTP Service Extension for Authentication, RFC 2554](https://tools.ietf.org/html/rfc2554)
 - [The PLAIN Simple Authentication and Security Layer (SASL) Mechanism, RFC 4616](https://tools.ietf.org/html/rfc4616)
 - [SMTP Service Extension for Secure SMTP over Transport Layer Security, RFC 3207](https://tools.ietf.org/html/rfc3207)
 - [SMTP Service Extension for Authentication, RFC 2554](https://tools.ietf.org/html/rfc2554)
 - [The PLAIN Simple Authentication and Security Layer (SASL) Mechanism, RFC 4616](https://tools.ietf.org/html/rfc4616)

-- [Simple Mail Transfer Protocol (SMTP) Service Extension for Delivery Status Notifications (DSNs)](https://tools.ietf.org/html/rfc3461)
+- [Simple Mail Transfer Protocol (SMTP) Service Extension for Delivery Status Notifications (DSNs), RFC 3461](https://tools.ietf.org/html/rfc3461)

 - [POP3 Extension Mechanism, RFC 2449](https://tools.ietf.org/html/rfc2449)
 - [POP3 Extension Mechanism, RFC 2449](https://tools.ietf.org/html/rfc2449)

diff --git a/docs/install.md b/docs/install.md
index 625608a2951fc85d783edd1026895fd0e9ddf058..89676153bd01027d38436f3510559d26028afd86 100644 (file)
--- a/docs/install.md
+++ b/docs/install.md
@@ -198,7 +198,7 @@ periodically via polling, so message delivery can seem slower than normal.
     - **Password:** The password you specified in `config.json`
     - Check **Secured connection using TLS**
 
     - **Password:** The password you specified in `config.json`
     - Check **Secured connection using TLS**
 

-Gmail will now let you send email as *mailbox@yourdomain.com*. But if you are replying to a message
-sent to *random@yourdomain.com*, you do not want the recipient to see the "mailbox" username in your
+Gmail will now let you send email as `mailbox@yourdomain.com`. But if you are replying to a message
+sent to `random@yourdomain.com`, you do not want the recipient to see the "mailbox" username in your

 reply. If you append `[sendas:random]` to the Subject line of the message, the SMTP server will
 change the From address to `random@yourdomain.com` and remove the special tag from the Subject line.
 reply. If you append `[sendas:random]` to the Subject line of the message, the SMTP server will
 change the From address to `random@yourdomain.com` and remove the special tag from the Subject line.