elmpoint.org

This repository contains the codebase for the updated Elm Point website. The most recent release represents the currently deployed version.

Links

• The beta site can be found here.
• See the Overall Progress board for most recent project status.
• See the Issue Tracker for the highest technical detail and most up-to-date progress (and to submit bugs).
• General discussion, feature suggestions, or open-ended questions can be added to the discussions board.

Contributing

Website editors can most easily make contributions through the website CMS (Content Management System). If you have website editing permissions, head to elmpoint.org/cms to get started.

To edit anything else not found in the CMS editor, you'll need a free Github account. Editing simple text or hard-coded items such as the sidebar links can be easily done on this Github site. More complex operations may require running the code locally.

Editing website data online

If you have a simple change to make to the website, the easiest way to contribute is here on Github.

For example, let's say you found a typo in a help message on the site.

1. Use the search function above to look for a snippet of the text you'd like to update. What you're looking for will be in the /client/src/ directory.
2. Click the pencil in the top right to edit the document online. Make your changes.
3. Click the green Commit changes... button.
   • In the popup screen, write a quick explanation of what you changed.
   • Click Propose changes, then Create Pull Request.
4. You are now shown the Pull Request created for you, which is where someone may comment on your change, make or suggest an additional revision, or merge the change directly into the website.

Running the code locally

For more complex changes, or if you'd like to create your own feature, you'll need to run the development server on your own computer.

1. Get the code. Fork the repository and clone your fork—see the PR guide below for more.

2. Download required software. To run the software, you'll need

   • Node.js - The most recent LTS version will probably work.
   • PNPM - This is the package manager that manages project dependencies. It is usually easiest to install with corepack.
   • SST Ion - This software is used to manage the server processing for the website. Pending a migration to the new version, please install using the bash script. Reference the deployment script for the correct version.
   • (recommended) Visual Studio Code - VSCode settings and extensions come with the project to get you running fastest.

3. Add AWS Credentials. In order to run build tests, SST uses an AWS account to manage a few assets in development. You'll need an AWS Account for this, but no created assets will surpass the standard AWS free tier.

   1. Create an AWS account if you don't already have one.

   2. Create an IAM user (tutorial) with administrator access.

   3. Register the IAM user in your environment. You can do this by creating the file client/.env, which should look like this:

   # if you only use this AWS account for this project...
   AWS_ACCESS_KEY_ID=abc123
   AWS_SECRET_ACCESS_KEY=abc123
   
   # -- OR --
   
   # if you have already regstered an AWS profile on your machine...
   AWS_PROFILE=your-profile-name-here

4. Create a Tiptap account. The site uses Tiptap for rich text editing, and they require that you create a free account to access their code. Follow Tiptap's instructions here to do so.

5. Install project dependencies. Run the following command in the root project folder to install the required dependencies:

   pnpm install
   

6. Configure to use the public API. Running the full Elm Point server locally requires substantially more setup and comfort with AWS, none of which is currently automated. It is much easier to instead use the public server API while you're working. To enable this, add the following line to the client/.env file:

   NEXT_PUBLIC_USE_PUBLIC_API=1
   

7. Run the development server. Open a terminal in the root project directory, and run:

   pnpm dev-client
   

8. Head to the development URL. Your terminal should tell you where to go, but it's probably http://localhost:3001/.

Using the API

The server API is accessible through a GraphQL endpoint, which is easiest to explore using the Apollo Editor (or any other introspection viewer.)

The endpoint above allows you to explore the available commands and documentation as is, but in order to run commands you'll need to add your authentication token like so:

You can find your authorization token in your browser's cookies.

Submitting local changes

If you've made local changes to the code, you'll need to manually submit a Pull Request for your code. Please follow standard Github Flow.

Helpful guides:

• Open Source Guide: Making a Pull Request - A general overview of the process.
• Musescore's "Git Workflow" - This is a great step-by-step guide to completing a contribution, including dealing with new changes that happen during your development.

The rough process:

1. Fork the repository. (click)
2. Clone your fork. git clone https://github.com/YOUR_USERNAME/epc-next.git
3. Create a branch for your update. git checkout -b name-of-your-update
4. Make and commit your changes. git commit
5. Push your changes to Github. git push
6. Create a Pull Request. do it manually or just go to your fork's homepage on Github—usually a banner appears to create an automatic PR.