Contributor's Guide

AW2 March 13, 2024

How to Contribute

Time / Effort

Contributors of time and expertise are very welcomed. Most content on the site is written in markdown, a simple text file format. It's pretty approachable, and works like discord. For example, using **asterisks** to bold text is markdown.

We have some adaptations to add Guild Wars 2 specific functionality of course, but most of the complexity will be working with github, the site that stores the files.

Financial

Of course, financial contributions are always welcome too, if that's preferred. We have a team set up on Liberapay, which is an open community funding platform based in France. All funds currently go towards development and hosting costs, but we hope to be able to offer honorariums to build contributors to recognize their efforts.

Other options such as GitHub Sponsors or Patreon are being considered. Reach out on discord if you prefer one of those options.

Content how to...

Accessibility Wars uses a static site generator. This means there is no database, no server-side scripts, and no way to edit directly on the site.

However, it is built from source code and contributors can make edits and submissions using GitHub's interface (or the git tool directly).


Setup


How to... edit

  1. Find a build to edit on the source repository.
  2. Click the markdown (.md) file to view it in the github editor
  3. Click the pencil icon to switch to edit mode, and make your changes
  4. Click the [Commit Changes...] button
  5. Give it a reasonable 1-line commit message and description of what was changed (Berdandy will be reading these so please make sense).

    Commit message: updated mad bomber mechanist to latest balance
    Extended description: old mad bomber mechanist was missing relics and needed a full trait rework

  6. Ensure your email is correct
  7. Ensure [Create a new branch for this commit and start a pull request] is selected.
    • the default name is very software oriented (username-patch-N), change it to make sense
    • Good example: mad-bomber-balance-update-jan-2024
    • Bad example: changed stuff
  8. Click [Propose changes]
    • This opens a pull request (git's terminology for a "request for the maintainer to pull your changes in")
    • Again, title and description. Title should be same as above. Add description if you wish
  9. Click [Create pull request]

From here, the maintainers (Berdandy) will get notified about the submitted changes and can merge them once reviewed. Keep an eye on your inbox and/or discord for possible modifications. After changes are accepted, the website builds and deploys. Usually less than 2 mins.


How to... preview

In short:

  1. install the custom site buider azola
  2. clone the source repository
  3. run azola serve
  4. go to http://127.0.0.1:1111 in your browser

That's basically it. It will automatically refresh whenever it detects changes.


How to... create

Method 1: copy/edit files

  1. clone the source repository with GitHub Desktop, gh, or just git. The following guide on pull requests is helpful if you’re new to pull requests or GitHub Desktop.
  2. find an existing build in builds
  3. duplicate the md file, changing name
  4. make all your edits, and preview changes
  5. add the file on github
  6. submit pull request
  7. turn on github notifications and wait for comments. If anything needs to be fixed, berdandy will message you using github
  8. if needed, fix issues, and push new changes to github, updating the pull request
  9. if all is good, it will be merged

Method 2: export

Follow the above steps, but instead of finding an existing build file and editing it, use the buildwars commandline tool in combination with an ArenaNet API Key (make one here), to export a character to our .md file format.

For example:

> buildwars API-KEY-GOES-HERE "Character Name" 1 1

Method 3: create on github web

This method doesn't require software installation, but the price is that you don't get to preview it, and it's much easier to upload broken content if you can't see it.

  1. create a (free) github account as per Setup above
  2. download a build .md file from the repository
  3. edit it to contain your new build with your favourite text editor
  4. in the builds directory, click Add File > Create New File, NOT Upload Files.
    Important! This may give you a warning about a need to make a Fork (which is a copy of the site). You want that.
  5. name the file. For example "my-awesome-warrior.md"
  6. paste the content of the new build file
  7. Click Commit Changes... and give it a commit message and description. This is for your own benefit of change history.
  8. Once you're satisfied with the preview, click Create pull request. The description here is for the reviewers (ie, berdandy).
    Important! ensure Allow edits by maintainers is checked
  9. turn on github notifications and wait for comments. If anything needs to be fixed, berdandy will message you using github
  10. if needed, fix issues, updating the pull request
  11. if all is good, it will be merged

Additional tools

These additional tools are useful. They will eventually be integrated, but for now, they're useful standalone utils.