This project has been built with the Apostrophe Boilerplate v2.x. For more documentation on Apostrophe, visit their documentation site.
-
Clone this repository to your local machine
-
Use NVM to match the
enginesproperty inpackage.json -
From a Terminal instance, run
yarnto install the dependencies -
Obtain a copy of the database and the assets from an admin.
⚠️ This requires that you have agreed with them beforehand.- Unzip the assets so they become the
public/uploadsdirectory - With the
*.tgzdatabase backup at the root of the project, runmongorestore --gzip --archive=<filename> --dropfrom a Terminal instance
- Unzip the assets so they become the
-
From a Terminal instance, run
yarn dev -
Open a browser, and go to http://localhost:3000/
Boy Scouts are supposed to leave a camping site in a better shape than it was when they arrived.
As such, developers also have that responsibility: leave the files onto which they worked in a better shape than they found it.
Obviously, this should apply only to the files onto which they work, so the scope of the work being done does not expand indefinitely. Any potential improvement discovered that are bigger than a quick fix should be listed in the project backlog.
Since development is a team effort, whether with current teammates, future teammates, or even your future self, you should always prefer clarity over cleverness. In broad strokes, this means ensuring to name your variables and methods in a constant and legible manner (e.g. avoiding one-letter variables), avoiding ternary expressions unless absolutely necessary, ensuring to add comments, etc.
Unless a necessary performance improvement is obtained by writing clever code that is complicated to read, it is best to avoid it. In the situation where it is necessary, ensure that you add appropriate comments to help your teammates.
Standardization of the coding style ensures that anyone understands the rules of engagement when joining the project. Ensure to you follow those rules as you develop.
See .eslintrc.json for the ESLint rules applied to this project, and also the .editorconfig files. Many IDEs implement linting functionalities. We leave those details to you.
Styles should be independent from HTML elements. The main reason for this is reusability, but also SEO, and accessibility.
-
Reusability: Declaring a style directly—e.g. on an
<button>—locks this style on this element, which may need to change according to context. What if an<a>needs to visually look identical to that button?
Styles should be declared in classes—e.g..btn—that can be reused and applied to whichever element. Those styles could then be extended—e.g.<a class="btn btn-primary">— so that their looks are appropriate to their context.
Ideally, those styles should even be declared in mixins for better reusability. -
SEO and accessibility: SEO ranking and accessibility depend on the semantics of the elements used, not on the style applied to them. As such, it should be easily possible to swap elements—e.g. an
<h2>for<div>—to be able to change the semantic meaning of the content, without changing its styling.
See the templates guidelines below for more details.
The id attribute of an HTML element is meant to create a variable so the element becomes reachable via JavaScript.
Instead, create a class, even if it is unique, for the element you would have styled with its id.
DRY coding should also apply to CSS. Breakpoints, colors, typography, components, etc. should as much as possible be defined once, and then imported, reused, and extended as needed.
In order to be consistent, CSS styling should also follow naming conventions. In short:
-
Use
lowerCamelCaseforid -
Use
snake-caseforclass
e.g.:
<button
id="clickableButton"
class="btn btn-primary"
>
Click here to click
</button>There may be different ways and languages that render templates: HTML, PHP, Twig, Mustache, etc. While they all have their idiosyncracies, they all intend to render HTML in a browser. The following guidelines make no distinction between those technologies and apply to all of them.
First and foremost, content on the web is about semantics, its meaning. As such, it is important to use appropriate HTML elements according to the intent of the content to display. This impacts not only SEO, but also accessibility.
Here are some rules of thumb:
-
Styling should never be defined by the HTML element used, this is the job of CSS.
-
All HTML content should be completely navigable by keyboard.
-
Do not freely interchange headings (
<h1>,<h2>, etc.) because you need bigger text or a subtitle.
Do use headings to structure content. -
Do not use
<a href="#">to trigger a JavaScript function on a page.
Do use a button.-
Hyperlinks lead to another page
-
Buttons do something on the same page
-
Read more about semantics and accessibility:
HTML tags can have multiple attributes added onto them. As such, lines can become quite long and unpleasant to investigate.
Ensure to break attributes onto different lines so that it can be easier to read, but also so that it is easier to see what changed when looking at the revision history.
<!--- avoid --->
<button id="clickableButton" class="btn btn-primary" onclick="onButtonClicked" onhover="onButtonHovered" disabled="false" data-value-1 data-value-2>Click here to click</button>
<!--- prefer --->
<button
id="clickableButton"
class="btn btn-primary"
onclick="onButtonClicked"
onhover="onButtonHovered"
disabled="false"
data-value-1
data-value-2
>
Click here to click
</button>With the proliferation of prerendered templates and JavaScript frameworks, it is more and more possible to render things conditionally in HTML.
This however oftentimes comes at the expense of legibility:
<!--- avoid --->
<button
disabled="{ model.parameter.value > model.otherParameter.value ? model.context.value : model.otherContext.value }"
>
Click here to click
</button>Ideally, declare all this logic in a method, and only use this method in the template. This makes the template more legible, and it also allows to create unit tests for this method.
<!--- prefer --->
<button
disabled="{!isButtonEnabled()}"
>
Click here to click
</button>
<script>
// model would be defined elsewhere
function isButtonEnabled() {
let isEnabled = false;
if (model.parameter.value > model.otherParameter.value) {
isEnabled = model.context.value;
} else {
isEnabled = model.otherContext.value;
}
return isEnabled;
}
</script>This project follows the Gitflow Workflow. In short:
-
The
masterbranch is work that is always functional to be pushed to a production server. -
The
developbranch is where work happens until the admin chooses to create a release. -
Feature branches are where each developer should work, branching off of the
developbranch, so that their changes are isolated and reviewed before being merged into the ongoingdevelopbranch. -
Contributors should always submit their work for review with a pull request (PR) and never push work directly to either the
developormasterbranch. Code administrators are responsible for reviewing PRs and are the only ones allowed to make direct commits to the main branches.
Ensure to standardize the branch names when creating a branch from develop.
<username>/<issueNumber>-<action>
Your username, e.g. "mjanson/".
This sorts the feature branches relative to who is working on it.
If there are more than one developer working on the feature branch, either user the name of the principal developer, or simply use "feature/" instead of the username.
Issues addressed should ideally have an entry in the issue list on GitHub. This allows to have a space to discuss the work to be done or completed.
The task which will be addressed, in imperative form, in the present tense. Ensure to use a short telegraphic sentence to describe the task.
-
mjanson/72-fix-header-search-form
-
feature/123-add-spanish-translation
-
Ensure to use dashes ("-") and not underscores to separate words.
-
Branch names should be in lowercase.
Ensure that you rebase when pulling work from the remote branches, so as to avoid a superfluous merge commits.
-
Git commits must be related to either an issue or a task, or at least with an explicit intention.
-
Do not simply commits a lot of changes at once that cover too many concerns.
-
Do not simply push commits to the
developbranch, work from a feature branch, and then ask for a pull request (PR).
Image: XKCD - Git Commit
For commits to be understood properly by all, here are some guidelines to write commit messages:
<sentence> (#<issueNumber>)
-
A short explanation of the work done, in sentence case, without a period at the end:
Fixed broken parsing
-
Write in past tense:
Fixed this issue
not
Fix this issue
The number of the issue this commit addresses, preceded by a number sign ("#"). Must be wrapped in brackets, and a space must preceded the brackets.
Ideally there should only be one per commit. In the case where there are many, the whole list of issue numbers should be wrapped in brackets, separated by a comma and a space (e.g. "(#1, #2, #3)"). Here also, a space must preceded the brackets.
-
Ensured search form leads to the search results (#72)
-
Added Spanish translation (#123)
-
Fixed home page layout (#1, #2, #4)
In the case where you need to add more details, keep the message short, and add the details in the commit body.
See the Git documentation as needed.