Skip to content

Latest commit

 

History

History
174 lines (124 loc) · 7.1 KB

CONTRIBUTORS.md

File metadata and controls

174 lines (124 loc) · 7.1 KB
Raw

Contributing to COMP/CON

Thank you for your interest!

The following is a set of guidelines for contributing to COMP/CON, the LANCER TTRPG digital toolkit. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].

What should I know before I get started?

First, dev discussion is mostly handled in the #comp-con channel of the Official LANCER Discord, and participation in that channel is a requirement for pull request acceptance. After your first accepted pull request, you'll get the Comp-Con Dev role.

To pull and build COMP/CON locally:

git clone [email protected]:massif-press/compcon.git
yarn
yarn serve

Which will open a browser window pointed to localhost:8080. Hot Module Reload is enabled, which means that the app should refresh as you save code. Occasionally (especially after certain syntax errors) this can start to fall off, in part or completely. If this is the case, a refresh will either get HMR working again or find your error.

If you need https support for your developer server, which is the case when you need to debug and develop on a machine other than your build machine, you can use the following command instead:

yarn serve-https

Please note this will cause your browser to display a warning about certificate validation, as the VUE developement certificate is self signed.

App Conventions

WIP

Design Decisions

WIP

How Can I Contribute?

Your First Code Contribution

Unsure where to begin contributing? You can start by looking through these beginner and help-wanted issues:

Commits

COMP/CON uses commitizen to produce a standard-version changelog. Pull requests that include commits that are not conventional commit formatted will not be accepted.

COMP/CON comes with a commitizen dev dependency, so when making commits use yarn commit instead of git commit, or use the VSCode Commitizen Support package.

COMP/CON currently has commitizen disabled due to issues generating changelogs, but it is intended to be re-enabled in the future. For now, please format commits and pull requests in a manner compliant with the conventional commit format for ease of reading and recording commits.

Pull Requests

WIP

Styleguides

Please adhere to eslint whenever possible. Prefer leaving warnings to adding ignores. Folder structure should reflect vue-router to the extent reasonable.

Typescript

  • src/io: Should contain any and all logic that touches the os -- file loading, checking appdata, etc
  • public:
    • static: Should just contain data, keep logic out (to the extent possible)
    • img: Files should be the onboard/stock images we want to copy over into appdata (see data io startup)

Classes

  • Maintain types to the extent possible.
  • Provide data interface when necessary (avoid any, in-function definitions).
  • Provide static Serialize and Deserialize functions if something needs to be saved.
  • Each class must be declared in its own file.
  • Import all classes into @/class, get classes from there instead of traversing the directory tree. (Out of date?)

Class Structure

  • Pilot
  • Mech
  • CompendiumItem
  • LicensedItem

Interfaces

  • Keep interface in class file when convenient.
  • Declare interface when useful (so, available globally).
  • Import nonglobal interfaces in @/interface. (Out of date?)

TODO: look into TS import() function in dec file to keep definitions with class, but make all interface available globally

Vue

UI should contain all reusable components. Everything starting with CC will be made available globally as cc-component-name.

Global component subcomponents (that don't themselves need to be available globally) should be prefixed by a _. Try to structure folders like:

  • topic/group - component type/set - components
  • _subcomponent.vue
  • CCMyComponentThatUsesSubcomponent.vue

Split views into collections of components wherever possible for easy reordering. Aim for DRY with components for stylistic consistency's sake (good refactor opportunities). Prefer two components with common subcomponents instead of bimodal components (eg. skillitem and skillselectitem).

CSS/Vuetify

  • LANCER book style before anything else. Adhere as close to the book as possible.
  • Fluff/flavor is important for the pilot management tools. No flavor (for now) for gm/encounter/campaign tools.
  • Compendium may get flavor later.

Accessibility

COMP/CON aims to be keyboard accessible. All buttons should be focusable with the tab key, respond to the enter key, and should have a noticeable highlight when tab-selected.

Often this happens automatically, but there are several ways to accidentally break accessibility, so it's important to check.

<!--Won't respond to enter key. Not tab selectable.-->
<div class="mx-2" @click="$emit('clicked')">
<!--Fix with response on @keydown.enter and added tabindex-->
<div class="mx-2" @click="$emit('clicked')" @keydown.enter="$emit('clicked')" tabindex="0">
<!--v-btns with `to` are turned into `a` elements without keyboard support.-->
<!--It might be nice to extend v-btn to fix that.-->
<v-btn to="/gm/mission/selector">
  <v-icon left>mdi-chevron-triple-left</v-icon>
  Return to Mission Menu
</v-btn>

<!--Fixed by moving `to` to a wrapper router-link-->
<router-link to="/gm/mission/selector">
  <v-btn text color="primary">
    <v-icon left>mdi-chevron-triple-left</v-icon>
    Return to Mission Menu
  </v-btn>
</router-link>

<!--Fixed with click event navigation instead of `to`-->
<v-btn text color="primary" @click="toMissions()>
  <v-icon left>mdi-chevron-triple-left</v-icon>
  Return to Mission Menu
</v-btn>
// ... later
methods: {
    toMissions() {
      this.$router.push('/gm/mission/selector')
    },
}
<!--Doesn't style keyboard focus, sometimes leaving keyboard focus invisible-->
.btn-main:hover {
  background-color: var(--v-active-base);
}
<!--Fix-->
.btn-main:hover,
.btn-main:focus {
  background-color: var(--v-active-base);
}

Usually these issues are trivial to fix, but easy to miss.

Please run through any new UI you create with keyboard only before pushing your work.

Additional Notes

Chores left:

  • integrate vue-class-component
  • testing