CONTRIBUTING.md

Why contribute to open source

What are your favourite Scala libraries?

Perhaps you like cats for functional programming, or build actor systems with Akka, or even dabble in machine learning with Spark. If nothing else, you must be keen on Scala itself. All of these libraries, along with almost all of the Scala ecosystem, are open source. Their code is publicly available to view, download and improve. Anyone can contribute changes to their codebases. Including you.

Open source codebases empower you to code the improvements you want to see. You can shape the libraries you use, and in turn shape the wider Scala ecosystem. Your contributions are valuable. Many smaller Scala projects stay alive through the work of new contributors. By making a useful change, however small, you play a crucial part in the Scala community.

If you’re unfamiliar to open source coding, this codebase is a great place to start. There are a wealth of small improvements to make, and we encourage you to suggest your own. The LSUG maintainers will happily walk you through the process of making code changes.

You don’t have to contribute to the Scala community through code — we’re also looking for volunteers to help organize events. Reach out here if you’d like to get involved.

How to contribute to this project

1. Introduce yourself in our Gitter chat room.

   We’ll help you with any issues you have.

2. Browse our issues board for a code change you’d like to make.

   If you have an improvement in mind, please write up a new issue for it.

3. If it’s your first time contributing to open source, take a look at the first-contributions project.

   This will walk you through the process of contributing to a GitHub repository.

4. Fork and clone this repository.

   These terms are explained in the first-contributions project. If you’re still not quite sure what they mean, head over to Gitter.

5. Setup the project.

6. Explore the codebase.

7. Learn how to work on it.

8. Make your code change.

   Comment on the issue to let us know you’re working on it, then head over to Gitter to chat about the details.

9. Make a pull request.

   The first-contributions project walks you through this process. As always, feel free to ask for help on Gitter.

10. Get it deployed.

    The LSUG maintainers will take a look at your code and suggest changes. Once we’re happy, we’ll merge and deploy it ourselves. You can then add your name to our contributors list.

Setup

Tools

This project requires quite a few tools to get up and running. Don’t worry if you aren’t familiar with them yet. If you have any trouble, head over to Gitter and let us know.

By this point, you should have already used GitHub, git and a terminal. If not, get set up with the first-contributions project.

You’ll now need to install the following tools.

• Mill
• Node.js
• Yarn

If you're already comfortable using a package manager (such as apt, homebrew or scoop), feel free to use it. If not, follow the steps below.

Mill

Download Mill. The most recently tested version is 0.8.0.

The mill installation instructions should work smoothly for Linux and Mac OS. Windows requires some more effort.

For Windows, download the assembly file:

• Follow the mill installation instructions
• Save the assembly file as mill.bat in the repository directory (this is probably called lsug-website).

Node.js

You can download an installer for a preferable version on downloads page. The most recently tested version is 10.

yarn

Download the installer for your OS. The most recently tested version is 1.22.

Source code editor

You will also need an IDE. If you’re undecided on one, we recommend VSCode with the following extensions:

• the Live Share Extension Pack
• Scala (Metals)
• Scala Syntax (official)
• GitLens

This will enable you to pair program with a maintainer, should you want to.

Checking your setup

The following mill commands need to be run in a terminal.

If you're using Windows, you must run mill --no-server instead of mill in command line. If you use Windows PowerShell use './mill' instead of 'mill'

Mill

Check you have mill installed.

• For MacOS and Linux, run:

  mill web.version

• For Windows, run in command line:

  mill --no-server version

This should print version of installed mill.

Scala

Check that the server tests pass.

• For MacOS and Linux, run:

  mill server.test

• For Windows, run:

  mill --no-server server.test

NodeJS and Yarn

Check you can bundle the client code and styles.

• For MacOS and Linux, run:

  mill web.bundle

• For Windows, run:

  mill --no-server web.bundle

IDE

You should have syntax highlighting and code completion in your IDE. If not, you might need specific setup to hook it up to mill. Follow mill’s guide on IDE support.

A first run

Start the website.

• For MacOS and Linux, run:

  mill web.run

• For Windows, run:

  mill --no-server web.run

You should see the output:

[59/60] server.run
16:39:09.492 [ioapp-compute-2] INFO org.http4s.blaze.channel.nio1.NIO1SocketServerGroup - Service bound to address /0:0:0:0:0:0:0:0:8080
16:39:09.492 [ioapp-compute-5] INFO org.http4s.blaze.channel.nio1.NIO1SocketServerGroup - Service bound to address /0:0:0:0:0:0:0:0:8443
16:39:09.497 [blaze-selector-0] DEBUG org.http4s.blaze.channel.nio1.SelectorLoop - Channel initialized.
16:39:09.497 [blaze-selector-0] DEBUG org.http4s.blaze.channel.nio1.SelectorLoop - Channel initialized.
16:39:09.498 [ioapp-compute-5] INFO org.http4s.server.blaze.BlazeServerBuilder -
  _   _   _        _ _
 | |_| |_| |_ _ __| | | ___
 | ' \  _|  _| '_ \_  _(_-<
 |_||_\__|\__| .__/ |_|/__/
			 |_|
16:39:09.498 [ioapp-compute-7] INFO org.http4s.server.blaze.BlazeServerBuilder -
  _   _   _        _ _
 | |_| |_| |_ _ __| | | ___
 | ' \  _|  _| '_ \_  _(_-<
 |_||_\__|\__| .__/ |_|/__/
			 |_|
16:39:09.512 [ioapp-compute-5] INFO org.http4s.server.blaze.BlazeServerBuilder - http4s v0.21.7 on blaze v0.14.13 started at http://[::]:8080/
16:39:09.512 [ioapp-compute-7] INFO org.http4s.server.blaze.BlazeServerBuilder - http4s v0.21.7 on blaze v0.14.13 started at https://[::]:8443/

This starts the server on ports 8080 and 8443. The server will run in your terminal, so you won’t be able to use it for anything else.

If you use MacOS, you may see the following message:

The MacOS firewall needs your approval before letting Java run applications on a port. Click Allow.

Navigate to https://localhost:8443/ in any browser. You should see a security warning:

We use a fake, hence insecure, certificate for local development. You can safely bypass the warning. This is done in different ways depending on your browser.

• In Firefox, click Advanced…, then Accept the risk and continue.
• In Chrome, click Advanced…, then Proceed to localhost (unsafe).
• Let us know if you have a different browser. We’ll update this list with better instructions.

Finally, you should see the website home page:

You can stop the website by pressing Ctrl-C in your terminal.

The Codebase

The main purpose of the LSUG website is to present information on LSUG events.

The website is made of two parts - the client and the server.

The client is written in ScalaJS - Scala that compiles to JavaScript - with the ScalaJS React web framework. It is responsible for the appearance and behaviour of the website.

The server is written in Scala using http4s. It is responsible for serving the website content. It decodes event details from files and delivers them to the client.

You can read about client-server architectures in depth on the MDN Web Docs.

The entire website is written in functional Scala. The code is unit tested in some areas, but we encourage you to write better tests.

Code structure

The project is laid out in four modules:

• client contains the website ScalaJS code
• server is responsible for serving the website and HTTP resources
• protocol contains the code shared between the two
• web is used for deployment and contains certain static assets

Terminology

The following terms are used throughout the codebase.

• A meetup is a gathering at which events are held.
• An event is a single talk or workshop taking place in a meetup.
• A speaker is a presenter or organizer of an event.
• markup is formatted text in a webpage.
• meetup dot com refers to meetup.com related information.

The client

The client’s behaviour is controlled by ScalaJS React. It has the several key components.

Component	Description	Example
lsug.ui.Home	The home page	https://www.lsug.co.uk
lsug.ui.meetup.Meetup	An upcoming meetup	https://www.lsug.co.uk/meetups/2019-08-21
lsug.ui.event.EventPage	A past event	https://www.lsug.co.uk/events/2019-08-21/0

The appearance is styled with SASS, found in the stylesheets directory.

The server

The server is a webservice responsible for providing the client with event-related information. You can view its API at https://www.lsug.co.uk/api/.

Event information is stored in .pm files in the resources directory. These files are written in a custom format inspired by the Pollen book publishing format. The server parses and decodes the event files into protocol data types, then serves these to the client. It also queries meetup.com to find the number of attendees for each event.

Local Development

The website is built using mill, a build tool for Scala.

Start it with:

mill web.run

Then navigate to https://localhost:8443/ to see it in action.

Command cheat sheet

• mill web.run starts the website.
• mill server.compile recompiles the server.
• mill -w web.bundle hot-reloads the client.

Working on the client

The client can be reloaded on the fly. You can keep the website running while you make code changes.

1. Start the website.
2. Bundle the JavaScript, styles and assets on the fly.

   mill -w web.bundle

   Any changes to the bundle will be compiled immediately.
3. Make changes to the client code or styles.
4. Reload https://localhost:8443/ in your browser. You should see your new changes.

Working on the server

The server cannot be reloaded on the fly. You’ll need to restart the website for your changes to take place.

1. Compile the server.

   mill server.compile

2. Test it.

   mill server.test

3. Start the website.
4. You should see your changes at https://localhost:8443/.

Working on the protocol

The protocol is used by the server, so also cannot be reloaded on the fly. You’ll need to restart the website to see your code changes.

1. Compile the server and client. These both use the protocol.

   mill server.compile
   mill client.compile

2. Test the server. This uses the protocol.

   mill server.test

3. Start the website.
4. You should see your changes at https://localhost:8443/

Maintainers

The LSUG website is maintained by Zainab Ali.