From c140a73055f933f68a8ad26b08b40d94f4c2f218 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 10 Oct 2024 05:01:57 +0000 Subject: [PATCH] Deployed 1b47cac with MkDocs version: 1.6.1 --- .nojekyll | 0 404.html | 792 ++ assets/images/favicon.png | Bin 0 -> 1870 bytes assets/javascripts/bundle.b425cdc4.min.js | 29 + assets/javascripts/bundle.b425cdc4.min.js.map | 8 + assets/javascripts/lunr/min/lunr.ar.min.js | 1 + assets/javascripts/lunr/min/lunr.da.min.js | 18 + assets/javascripts/lunr/min/lunr.de.min.js | 18 + assets/javascripts/lunr/min/lunr.du.min.js | 18 + assets/javascripts/lunr/min/lunr.es.min.js | 18 + assets/javascripts/lunr/min/lunr.fi.min.js | 18 + assets/javascripts/lunr/min/lunr.fr.min.js | 18 + assets/javascripts/lunr/min/lunr.hi.min.js | 1 + assets/javascripts/lunr/min/lunr.hu.min.js | 18 + assets/javascripts/lunr/min/lunr.hy.min.js | 1 + assets/javascripts/lunr/min/lunr.it.min.js | 18 + assets/javascripts/lunr/min/lunr.ja.min.js | 1 + assets/javascripts/lunr/min/lunr.jp.min.js | 1 + assets/javascripts/lunr/min/lunr.kn.min.js | 1 + assets/javascripts/lunr/min/lunr.ko.min.js | 1 + assets/javascripts/lunr/min/lunr.multi.min.js | 1 + assets/javascripts/lunr/min/lunr.nl.min.js | 18 + assets/javascripts/lunr/min/lunr.no.min.js | 18 + assets/javascripts/lunr/min/lunr.pt.min.js | 18 + assets/javascripts/lunr/min/lunr.ro.min.js | 18 + assets/javascripts/lunr/min/lunr.ru.min.js | 18 + assets/javascripts/lunr/min/lunr.sa.min.js | 1 + .../lunr/min/lunr.stemmer.support.min.js | 1 + assets/javascripts/lunr/min/lunr.sv.min.js | 18 + assets/javascripts/lunr/min/lunr.ta.min.js | 1 + assets/javascripts/lunr/min/lunr.te.min.js | 1 + assets/javascripts/lunr/min/lunr.th.min.js | 1 + assets/javascripts/lunr/min/lunr.tr.min.js | 18 + assets/javascripts/lunr/min/lunr.vi.min.js | 1 + assets/javascripts/lunr/min/lunr.zh.min.js | 1 + assets/javascripts/lunr/tinyseg.js | 206 + assets/javascripts/lunr/wordcut.js | 6708 +++++++++++++++++ .../workers/search.208ed371.min.js | 42 + .../workers/search.208ed371.min.js.map | 8 + assets/logo-horizontal.svg | 23 + assets/responsive.gif | Bin 0 -> 502471 bytes assets/scalable.gif | Bin 0 -> 796744 bytes assets/scale-and-response.gif | Bin 0 -> 599596 bytes assets/stylesheets/main.26e3688c.min.css | 1 + assets/stylesheets/main.26e3688c.min.css.map | 1 + assets/stylesheets/palette.ecc896b0.min.css | 1 + .../stylesheets/palette.ecc896b0.min.css.map | 1 + css/extra.css | 4 + developer/backend/index.html | 1005 +++ developer/design-system/index.html | 1442 ++++ developer/development-culture/index.html | 1004 +++ developer/devops/index.html | 1214 +++ developer/frontend/index.html | 1303 ++++ developer/github/index.html | 957 +++ developer/installation/index.html | 1136 +++ developer/mkdocs-architecture/index.html | 1111 +++ developer/mkdocs-edit-instructions/index.html | 947 +++ developer/mkdocs-guide/index.html | 944 +++ index.html | 926 +++ joining-the-team/content-writer/index.html | 840 +++ joining-the-team/data-scientist/index.html | 837 ++ joining-the-team/intro/index.html | 935 +++ joining-the-team/other-volunteer/index.html | 837 ++ joining-the-team/product-manager/index.html | 847 +++ joining-the-team/uiux-designer/index.html | 907 +++ joining-the-team/uiux-researcher/index.html | 893 +++ joining-the-team/web-developer/index.html | 913 +++ js/extra.js | 75 + misc/ada-guide/index.html | 925 +++ misc/glossary/index.html | 848 +++ misc/history/index.html | 913 +++ misc/our-process/index.html | 828 ++ misc/research-wiki-template/index.html | 851 +++ misc/security-updates/index.html | 829 ++ misc/the-team/index.html | 901 +++ resources/index.html | 1031 +++ search/search_index.json | 1 + sitemap.xml | 111 + sitemap.xml.gz | Bin 0 -> 464 bytes 79 files changed, 34420 insertions(+) create mode 100644 .nojekyll create mode 100644 404.html create mode 100644 assets/images/favicon.png create mode 100644 assets/javascripts/bundle.b425cdc4.min.js create mode 100644 assets/javascripts/bundle.b425cdc4.min.js.map create mode 100644 assets/javascripts/lunr/min/lunr.ar.min.js create mode 100644 assets/javascripts/lunr/min/lunr.da.min.js create mode 100644 assets/javascripts/lunr/min/lunr.de.min.js create mode 100644 assets/javascripts/lunr/min/lunr.du.min.js create mode 100644 assets/javascripts/lunr/min/lunr.es.min.js create mode 100644 assets/javascripts/lunr/min/lunr.fi.min.js create mode 100644 assets/javascripts/lunr/min/lunr.fr.min.js create mode 100644 assets/javascripts/lunr/min/lunr.hi.min.js create mode 100644 assets/javascripts/lunr/min/lunr.hu.min.js create mode 100644 assets/javascripts/lunr/min/lunr.hy.min.js create mode 100644 assets/javascripts/lunr/min/lunr.it.min.js create mode 100644 assets/javascripts/lunr/min/lunr.ja.min.js create mode 100644 assets/javascripts/lunr/min/lunr.jp.min.js create mode 100644 assets/javascripts/lunr/min/lunr.kn.min.js create mode 100644 assets/javascripts/lunr/min/lunr.ko.min.js create mode 100644 assets/javascripts/lunr/min/lunr.multi.min.js create mode 100644 assets/javascripts/lunr/min/lunr.nl.min.js create mode 100644 assets/javascripts/lunr/min/lunr.no.min.js create mode 100644 assets/javascripts/lunr/min/lunr.pt.min.js create mode 100644 assets/javascripts/lunr/min/lunr.ro.min.js create mode 100644 assets/javascripts/lunr/min/lunr.ru.min.js create mode 100644 assets/javascripts/lunr/min/lunr.sa.min.js create mode 100644 assets/javascripts/lunr/min/lunr.stemmer.support.min.js create mode 100644 assets/javascripts/lunr/min/lunr.sv.min.js create mode 100644 assets/javascripts/lunr/min/lunr.ta.min.js create mode 100644 assets/javascripts/lunr/min/lunr.te.min.js create mode 100644 assets/javascripts/lunr/min/lunr.th.min.js create mode 100644 assets/javascripts/lunr/min/lunr.tr.min.js create mode 100644 assets/javascripts/lunr/min/lunr.vi.min.js create mode 100644 assets/javascripts/lunr/min/lunr.zh.min.js create mode 100644 assets/javascripts/lunr/tinyseg.js create mode 100644 assets/javascripts/lunr/wordcut.js create mode 100644 assets/javascripts/workers/search.208ed371.min.js create mode 100644 assets/javascripts/workers/search.208ed371.min.js.map create mode 100644 assets/logo-horizontal.svg create mode 100644 assets/responsive.gif create mode 100644 assets/scalable.gif create mode 100644 assets/scale-and-response.gif create mode 100644 assets/stylesheets/main.26e3688c.min.css create mode 100644 assets/stylesheets/main.26e3688c.min.css.map create mode 100644 assets/stylesheets/palette.ecc896b0.min.css create mode 100644 assets/stylesheets/palette.ecc896b0.min.css.map create mode 100644 css/extra.css create mode 100644 developer/backend/index.html create mode 100644 developer/design-system/index.html create mode 100644 developer/development-culture/index.html create mode 100644 developer/devops/index.html create mode 100644 developer/frontend/index.html create mode 100644 developer/github/index.html create mode 100644 developer/installation/index.html create mode 100644 developer/mkdocs-architecture/index.html create mode 100644 developer/mkdocs-edit-instructions/index.html create mode 100644 developer/mkdocs-guide/index.html create mode 100644 index.html create mode 100644 joining-the-team/content-writer/index.html create mode 100644 joining-the-team/data-scientist/index.html create mode 100644 joining-the-team/intro/index.html create mode 100644 joining-the-team/other-volunteer/index.html create mode 100644 joining-the-team/product-manager/index.html create mode 100644 joining-the-team/uiux-designer/index.html create mode 100644 joining-the-team/uiux-researcher/index.html create mode 100644 joining-the-team/web-developer/index.html create mode 100644 js/extra.js create mode 100644 misc/ada-guide/index.html create mode 100644 misc/glossary/index.html create mode 100644 misc/history/index.html create mode 100644 misc/our-process/index.html create mode 100644 misc/research-wiki-template/index.html create mode 100644 misc/security-updates/index.html create mode 100644 misc/the-team/index.html create mode 100644 resources/index.html create mode 100644 search/search_index.json create mode 100644 sitemap.xml create mode 100644 sitemap.xml.gz diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 00000000..e69de29b diff --git a/404.html b/404.html new file mode 100644 index 00000000..9754a859 --- /dev/null +++ b/404.html @@ -0,0 +1,792 @@ + + + +
+ + + + + + + + + + + + + +├── .github/
+│ └── ISSUE_TEMPLATE/
+├── app/ # Backend
+│ ├── config/ # Backend
+│ └── settings.py
+│ ├── frontend/ # Backend
+│ ├── server/ # Backend
+│ ├── .babelrc
+│ ├── manage.py
+│ ├── requirements.txt # Backend
+│ ├── package.json
+│ ├── package-lock.json
+│ └── webpack.config.js
+├── dev/
+│ ├── django.dockerfile
+│ ├── webpack.dockerfile
+│ └── dev.env
+├── .dockerignore
+├── .gitignore
+├── jsconfig.json
+├── CONTRIBUTING.md
+├── docker-compose.yml
+├── LICENSE
+└── README.md
+
+Overall project structure
├── config/
+│ ├── <Django Project Files>
+├── frontend/
+│ └── <Django App Files>
+├── server/
+│ ├── <Django App Files>
+│ ├─── <RESTFramework Files>
+| └── templates
+├── manage.py
+└── requirements.txt
+
+Backend Architecture
These diagrams show how data flows through the app: Frontend and Backend UML diagrams
+Backend Tech Stack: Django, DjangoRESTFramework
+The backend architecture is consists the the Django config/
project, and the frontend/
and server/
Django apps. In addition to serving as part of our backend, the frontend/
directory also serves our frontend architecture. More about the frontend/
directory as it relates our frontend architecture can be found in our guide on Frontend Architecture.
frontend/
and server/
. Within these directories are the default <Django App Files>
that are created with every app as well as <RESTFramework Files>
.serializers.py
, these files are additional files that support Django via the DjangoRestFramework library.package.json
.├── migrations/
+│ └── __init__.py
+├── __init__.py
+├── admin.py
+├── apps.py
+├── models.py
+├── tests.py
+├── urls.py
+└── views.py
+
+Files generated by Django when creating a new Django app
These files uses DjangoRestFramework in order to quickly create an API. The most often editted files here are models.py
, urls.py
, and views.py
. The models define the schema for our database tables. Once the models are made, they are router to views.py where the data is transformed and exposed to our API. It is in views where we create handlers to manage REST operations.
Please refer to Django's documentation for more information.
+├── serializers.py
+
+RESTFramework files used to create a Django REST API
Serializers turn the data from the database into a Python-readable form.
+Please refer to DjangoRESTFramework's documentation for more information.
+This guide is the developer documentation for the CivicTechJobs Design System (CTJ-DS). Inside is not only an overview of our components, but also usage tips, and strategies to translate Figma designs into components for flexible, dynamic web pages.
+To understand our Design System, these are some overarching concepts to keep in mind when working with the DS.
+UI designers specialize in turning project requirements into graphical interfaces that fits project requirements. Designers, however, are not coders. As a result, here are some development-related aspects of componentization that designers do not consider:
+Because of these factors, the way a prototype is built on Figma does not necessarily translate 1:1 to how the designs should be build as code. For example, Figma designs does not use SCSS mixins to simplify code or percentages as units of size.
+Likewise, we must contend with the fact that Figma designs are static screens tied to very specific viewport sizes. As developers we need to recreate the Figma designs while also considering the intent behind a design.
+As a developer, we need to effectively communicate with designers at multiple stage of the Figma design process. This means providing recommendations or alternatives that are simpler and easier for the developer to implement and maintain.
+At CivicTechJobs, designers use two standard viewport widths when creating our UIs: 1440px for desktop and 375px for mobile. The appearance of the UI beyond these two sizes are determined by us, as developers, as we componentize the Figma designs. Do note though that our screen size of interest changes depending on the stage of our project. Right now, our current size of interest is:
+1025px and up (or, laptop and up)
+
+When creating or using components, it is good to keep in mind the differences between a scalable component and responsive component.
+A scalable component:
+These columns show scalable behavior. The columns smoothly shrink and grow with the screen size.
A responsive component:
+These buttons show responsive behavior. The buttons do not change until the screen reaches a certain breakpoint.
Scalability and responsiveness are not mutually exclusive. A web page can contain both scalable and responsive components. As a matter of fact, a single component can be both responsive and scalable.
+ +This card shows both scalable and responsive behavior. The width smoothly change with the screen size, but drastically changes at our max small tablet breakpoint.
Only by combining both scalability and responsiveness in our design, can we create a high-quality site. When translating from Figma to code, most of the time, the work is in deciding what part of the Figma design should scale, and what part should be responsive. As a rule of thumb, when designing the transition from the desktop to mobile Figma, scale down empty space and margins, and responsively shrink buttons and text.
+As a small project, React recommends the use of PropTypes as our type checking library.
+By using PropTypes, we have an easy way to look up hints on how to use our components.
+Button.propTypes = {
+ addClass: PropTypes.string,
+ color: PropTypes.oneOf(["primary", "primary-dark"]),
+ disabled: PropTypes.bool,
+ href: PropTypes.string,
+ length: PropTypes.oneOf(["", "long"]),
+ onClick: PropTypes.func,
+ size: PropTypes.oneOf(["sm", "md", "lg", "icon"]),
+ target: PropTypes.oneOf([
+ "_blank",
+ "_self",
+ "_parent",
+ "_top",
+ PropTypes.string,
+ ]),
+};
+
+For this <Button> component, PropTypes provide clues on the component's props. From these hints, a developer can guess that a small, long button would be declared as <Button size="sm" length="long">
Because comprehensive documentation is difficult for a small team to maintain, we rely on PropTypes and cleanly written code to provide clues on how to use each component. We recommend new developers take time to play with the components in components/
to fully understand how to utilize them. You can use the /demo web endpoint and Demo.js when developing to play around with our components.
While we can use pure CSS as our styling sheet, using SCSS with React components allows us to standardize our components in a powerful way. Componentization allows:
+Because of these benefits, we use a component-first approach to developing web pages. Please componentize as much as possible and use them to build high-quality web pages!
+As a note, the DS is put together based on industry trends and practices. If you have ever explored Bootstrap, MUI, or Atlassian Design System, you will see many similarities between their components and ours.
+Most of our styles have a class and mixin equivalent. The class, for the most part, is created from just declaring the mixin inside the class.
+@mixin hidden {
+ display: none;
+}
+
+.hidden {
+ @include hidden;
+}
+
+Above is the hidden mixin definition. Below is the hidden mixin declaration as part of the .hidden class.
These are both provided to suit different use cases. For example, the class version is best suited for declaring inside of React components or HTML elements as part of the addClass
prop or className
attribute. On the other hand, the mixin version is best used when adding it to your own custom style, such as with media queries.
.my-own-custom-class {
+ @include breakpoint-media-max("smtablet") {
+ @include hidden; // Do this
+ @extend .hidden; // Do not do this, will break
+
+ @include col-size(6); // Do this
+ @extend .col-6; // Do not do this, will break
+ }
+}
+
+Please use the mixin version when you want your own custom style to inherit from an existing style!
As with most design systems, we use a standard 12-column system to subdivide our layouts. Each column, without spacing, is worth *8.33% of its container's width**. This means that columns are, by default, scalable.
+To use of our column classes, first declare a parent container with the .flex-container
class. Then use col-*
classes in each children, replacing the *
with the number for the column size.
We need to use a parent .flex-container
with col-*
classes to subdivide the UI.
Our 12-column system can be used in conjunction with .row
and nested .col-*
to further subdivide the UI, and create more complex layouts.
With .flex-container
, .row
, and .col-*
, we can create complex layouts that fit our purposes.
++*Note: Although Figma uses 12 columns to subdivide the entire screen, our column classes subdivides the container. This means that we can divide the whole screen into columns, and then divide each column even further to achieve our desired ratios.
+
++"99% of the time, you'll want to reclaim space from padding, margins, or empty space as screen size shrinks."
+
The spacing utilities are classified by attributes and size.
+Table of Spacing Attributes
+Spacing attribute (margins) | +Meaning | +| | +Spacing attribute (padding) | +Meaning | +
---|---|---|---|---|
m | +all margins | +| | +p | +all paddings | +
mt | +margin-top | +| | +pt | +padding-top | +
mr | +margin-right | +| | +pr | +padding-right | +
mb | +margin-bottom | +| | +pb | +padding-bottom | +
ml | +margin-left | +| | +pl | +padding-left | +
mx | +margin-left and -right | +| | +px | +padding-left and -right | +
my | +margin-top and -bottom | +| | +py | +padding-top and -bottom | +
Table of Spacing Sizes
+Spacing size | +Actual size (px) | +
---|---|
0 | +0px | +
1 | +8px | +
2 | +16px | +
3 | +24px | +
4 | +32px | +
5 | +40px | +
Tables showing the different way we classifies our spacing utilities. As an example, .px-4
sets the left and right padding as 32px.
Because our DS is based on a 12-column system, spacing utilities are made such that adding them on would not alter the 12-column system. For that reason, it is optimal to use the spacing utilities whenever possible over setting custom margins or padding.
+ + +Add margins responsibly. Try to use the spacing utilities over creating custom margin classes.
As an example, if Figma indicates a 10px left margin, use either .ml-1
or .ml-2
. Other times, however, Figma designs show spacing that falls outside of our size range. In this scenario, rather than set a specific margin, try to use centering instead, as large spaces are usually not a result of spacing, but of centering.
By being smart about the way we include spacing, we ensure scalability and reduce the maintenance cost of our code.
+++"When using responsive mixins, order matters! Always declare them from big to small."
+
Several of our components have *-responsive
mixins at the end of the .scss
file. These act as helpers to quickly create responsiveness into our components, keeping our code simple to understand.
These mixins always use max-width in its media query (as we use a desktop-first approach), so order matters! To use them properly, specify a default* and declare screen size from largest to smallest:
+ + +DO: specify a default on top and declare *-responsive
mixins from large to small screen sizes.
DON'T: declare *-responsive
mixins without a default on top or from a smaller to larger screen size.
++*Note: There is one caveat to that as some components come with their own default. For example, buttons take a size prop, in which you declare a default already. Therefore when using the responsive mixin for button size, there is no need to declare a top level default in the scss code.
+
SVG assets are read into our codebase as React components (or inline SVG) or data-urls.
+As React components:
+As Data-urls:
+img
tags, to allow quick width/length adjustments?url
qualifiers// COP Icons
+import CopIconData from "./svgs/cop-icon-datascience.svg";
+import CopIconEngineering from "./svgs/cop-icon-engineering.svg";
+import CopIconOps from "./svgs/cop-icon-ops.svg";
+import CopIconProduct from "./svgs/cop-icon-product.svg";
+import CopIconUiux from "./svgs/cop-icon-uiux.svg";
+
+import copIconData from "./svgs/cop-icon-datascience.svg?url";
+import copIconEngineering from "./svgs/cop-icon-engineering.svg?url";
+import copIconOps from "./svgs/cop-icon-ops.svg?url";
+import copIconProduct from "./svgs/cop-icon-product.svg?url";
+import copIconUiux from "./svgs/cop-icon-uiux.svg?url";
+
+The top icons are imported from the image file as SVG components (or inline SVG). The bottom icons are the same file imported as data-urls. Notice how the latter import file adds "?url".
When using our SVG assets make sure to use the best import for the job. In some cases, however, neither of these imports are optimal to use. For example the SVG itself might be incorrectly formatted.
+ +This SVG contains extra spaces, especially on the bottom. This image is impossible to center correctly without adding unnecessary margins.
In this case, rather than calculating some difficult to maintain, complex spacing, simply request the design team to provide a better SVG or edit the SVG yourself and send a copy to the design team.
+This happens when @extend is used inside of media queries. An example using our DS,
+.header-logo-desktop {
+ @include breakpoint-media-max("smtablet") {
+ @extend .hidden;
+ }
+}
+
+Using @extend inside of a media query will result in an error. Instead, use a mixin declaration with @include instead. Most classes in the DS include an equivalent mixin for this specific purpose.
.header-logo-desktop {
+ @include breakpoint-media-max("smtablet") {
+ @include hidden;
+ }
+}
+
+This works because it declares a mixin rather than extend the class!
To avoid these errors, it is encouraged to use the mixin rather than the class version of a specific style for inheritance whenever possible!
+For more information visit this documentation and this Stack Overflow question.
+Atomic Design
+Atlassian Design System
+Bootstrap
+Material-UI
Note: If embeds are out-of-date, and you have no access to the originals, please fork and replace them through CodeSandbox!
+ + + + + + + +At CivicTechJobs, the developers of our team have 3 key tasks:
+This guide will discuss how each of these work at CivicTechJobs. If you have any questions be sure to let us know! We strive to create an inclusive space for developers to learn and achieve their goals.
+++To make an issue, follow this guide from GitHub, or take a look at this section of the CONTRIBUTING.md.
+
At CivicTechJobs, updating the project starts with creating an issue outlining the situation and changes needed to resolve the situation. When writing an issue, a good rule of thumb is to write as if another developer would be the one to work on the issue. Therefore, being thorough is better than brief. Some good guidelines to follow:
+After writing out the issue, be sure to add labels. At minimum, we need three labels, one each from the "size", "role" and "feature/p-feature" series. In most cases, you should not create your own label. If you are unsure what labels to place, it is okay to leave it be, as another team member will help you when they notice the issue lacks certain labels.
+Once an issue is created, and placed in the Project Management project board, the developer is mostly done with the issue. If the issue contains a dependency, it will move into the "Ice Box" column via GitHub automation, or "New Issue Approval", otherwise.
+On rare occasions, a project manager, or other team members, might ping you with questions on the issue. Perhaps the team member did not understand the jargon, or the instructions were unclear. In that case, read their concerns carefully and either answer with a comment, or edit the original issue. Eventually, the issue will be approved, prioritized, and released into the "Prioritized Backlog" column, where developers can work on it.
+++To resolve an issue, take a look at this section of the CONTRIBUTING.md.
+
When choosing an issue to work on from the "Prioritized Backlog" column, it is good to note the "role" and "size" label. This signals the expertise required and time commitment needed to resolve the issue. As a rule of thumb, a smaller issue should take a week, and a larger issue, two or three weeks. This should give you a good idea on what issues is best for you to take at the moment. If you are completely new, we recommend taking smaller issues to understand your limits before pushing them further. That said, you are free to work on whatever you want.
+On occasion, when an issue is being worked on for an inordinate amount of time, the team might request an update on your progress. When giving your progress, it is courteous to give an ETA on the issue, and evaluate on your ability to resolve the issue in a reasonable timeframe. If an issue is taking far too long, it might be wise to abandon the issue and work on something that might bring more value to you and the team.
+Also, one final note: Do not contact the team via email or Slack to review your pull request unless it as been 72 hours since it was opened! The team will occasionally comb for pull requests and review them. If you want to move on to another issue, consider reviewing another developer's pull request (if you are part of the team), contribute to other open source projects, or ask the team for additional tasks.
+Most issues can be divided into two broad types: frontend issues, and backend issues.
+When working on frontend issues, there will usually be a link to the Figma design. Figma often contains multiple prototypes and future prototypes. When looking for our current design, go to the bottom right corner and look for a pink rectangle. Anything within that represents our most up-to-date design. Use that as a reference for your frontend issues. If the pink rectangle is not there, please request the UI design team to put a pink rectangle on the latest approved design.
+On rare circumstances, designs can change in the middle of work. This is something that happens as part of development, but will often be telegraphed during meetings. If a design change, you are free to reassess and abandon your current issue, or code pragmatically to ensure your work would not need a massive overhaul.
+++To review code, please take a look at this GitHub documentation, and this portion of our CONTRIBUTING.md.
+
Code that should be reviewed is found in the pull request tab. These are issues that require someone to look over for several criteria:
+When code meets all three criteria, it can then be merged and made a part of the site. Otherwise, the review should indicate changes that needs to be made.
+As an advanced project, CivicTechJobs have certain expectations for our developers. One of these is that issues of size 1 or 2 is small enough that we "pre-review" them. This means that we are confident that the developer can resolve these issues without review. Therefore, these issues can be merged directly into our codebase upon resolution. That said, it is still fine to request the team to review your code if feedback is desired.
+Important: Although issues can be pre-reviewed, do not make a habit of merging without making a pull request. There will be times when you performed an accidental merge, which could be a pain to fix on the command-line.
+As one final note, code can be merged solely on one approved review but it is fine to request more reviewers or ask for the team to review it during a developer meeting.
+ + + + + + +├── .github/
+│ └── ISSUE_TEMPLATE/
+├── app/
+│ ├── config/
+│ └── settings.py
+│ ├── frontend/
+│ ├── server/
+│ ├── .babelrc
+│ ├── manage.py
+│ ├── requirements.txt
+│ ├── package.json
+│ ├── package-lock.json
+│ └── webpack.config.js
+├── dev/ # DevOps
+│ ├── django.dockerfile
+│ ├── webpack.dockerfile
+│ └── dev.env
+├── .dockerignore # DevOps
+├── .gitignore
+├── jsconfig.json
+├── CONTRIBUTING.md
+├── docker-compose.yml # DevOps
+├── LICENSE
+└── README.md
+
+Overall project structure
├── dev/
+│ ├── django.dockerfile
+│ ├── webpack.dockerfile
+│ └── dev.env.example
+├── .dockerignore
+├── docker-compose.yml
+├── alias-config.txt
+└── alias.sh
+
+DevOps Architecture
DevOps Tech Stack: Docker, Gunicorn, Nginx, PostgreSQL, test
+Our devops files can be thought of as a set of files needed to create an exact replica of our environments for our developers. Although the overall structure appears deceptively basic, it only represents a fraction of our devops files. Several of our files, such as the ones that construct our staging environment, contains sensitive information, and as such as not placed in our public repository. For most frontend and backend work, there is never a need to access these files.
+++*Note: On the rare occasions that there is a need to access the sensitive files for environments other than development, please consult the development lead of the project. They will know exactly what files you need, and what permissions you need to access them.
+
django.dockerfile
contains information for our Django server setup. webpack.dockerfile
contains information to start our webpack watch plugin. dev.env.example
is an example of the env file needed to configure our dev environment.alias-config.txt
Docker is a platform that allows packaging and virtualizing applications within a container. This gives developers the powerful ability to collaborate in a stable, synchonized environment, and deploying web applications with the greatest of ease. We will not be going too much into Docker here, but we will explain in greater depth some of the Docker configurations we have made.
+docker-compose.yml
This file contains configuration directions for docker compose. It consists of three services: pgdb (our database), webpack (our webpack bundler), and django (our django server). The webpack and django service relies in separate dockerfiles, located in the dev
directory to build the container. This separation of dockerfiles enable each container to be build with its own set of dependencies. It also makes rebuilding the container simple when dependencies are migrated to a newer version.
For those of you used to creating applications without Docker, most would run webpack and django in separate terminals, so that they can both run at the same time. For the purposes of brevity, the different services can be considered to be Docker's way of running separate terminals.
+One will also notice that the Django command uses a placeholder server name, 0.0.0.0:8000. This placeholder is important, since Docker creates an isolated environment. As a result, servers that are run in Docker does not recognize a browser from outside of that environment. Without this server name, localhost:8000 will not reach the server, as the server would recognize your browser as coming from a foreign machine. Therefore, all warnings related to 0.0.0.0, should they pop-up, should be ignored.
+*.dockerfile
Dockerfiles are files that define how a container is built. Although containerization is a deep concept, to put it briefly, you can think of containers as separate "mini-computers", each programmed to do one thing. Some containers, such as our pgdb
container does not require a dockerfile to configure it, as it works out of the box. On the otherhand, our webpack
and django
containers need dockerfile to built out the files we need to run it effectively.
FROM node:latest
+
+WORKDIR /code
+
+
+# install app dependencies
+COPY ./package.json ./
+COPY ./package-lock.json ./
+RUN npm install
+
+
+# add app
+COPY . .
+
+Sample dockerfile that copies the package.json from a project and installs all dependencies.
Dockerfiles are usually named as just dockerfile
, as that is the default name that docker looks for when constructing our builds. Since our project requires multiple dockerfiles, we name them with .dockerfile
extensions, a convention that allows VSCode to detect dockerfiles and use appropriate syntax highlighting.
Do note that docker and dockerfiles can be fickle to work with, especially on old devices. Further down this documentation are various tips and commands that can be used with docker to help debug your code. But as always, consulting official documentation is the best way to get accurate, up-to-date information.
+Our development environment is entirely defined by our docker-compose.yml
, and the files inside of dev/
. More information about those files can be found above.
Of note, however, is the dev.env.example file. This file is only a sample, but lists out all the environmental variables needed to run our site. While most of them are prefilled, some uses <>
to indicate placeholders, which must be filled in by the developer.
More information on our staging files can be found with our staging files. To access this information, please ask for the required permissions from the development lead.
+docker compose down -v
+
+Useful to completely remove a container and related volumes. This is helpful when fiddling with database settings, which often breaks the database. This command allows the container to be restarted fresh.
+docker compose -f <filename> <docker command>
+
+Use this to specify an alternate docker-compose file to run your commands, such as docker-compose-other.yml. This is useful if you want to test out docker for yourself.
+docker compose run <container> <command>
+
+This is useful to run one time commands inside your container. Some good commands to run are:
+docker exec -it <container> sh
+
+Use this to do heavier debugging inside of your container. What this does is open the shell inside of the container's "mini-computer". This allows you to explore the files inside the container to see if it matches what you would expect after building is finished. This command only works when a container is running, so use docker compose run -d
to run your container in the background beforehand.
docker compose build --progress=plain
+
+Sometimes when a build is happening, the logs are too opaque to debug if a step goes wrong. This commands makes the logs a bit more verbose so that you might have an easier time debugging.
+For convenience, we have created a shell script that allows for longer commands to be executed with less typing. The script is capable of executing any of the commands listed in alias-config.txt
without having to type out the entire command.
alias.sh
To use this script, run bash alias.sh $arg
or ./alias.sh $arg
where $arg
is the alias of the command you wish to execute. For example, try running bash alias.sh test
.
alias-config.txt
This file contains many of the important commands you will need when developing for this project. Note that each command starts with a single word followed by a :
and then a command. You must follow this pattern when adding additional commands to the file. Please note that any docker run
commands must use the -T
flag to allocate a pusedo-TTY or the command will not work.
├── .github/
+│ └── ISSUE_TEMPLATE/
+├── app/
+│ ├── config/
+│ └── settings.py
+│ ├── frontend/ # Frontend
+│ ├── server/
+| ├── tests/ # Frontend
+| ├── .babelrc # Frontend
+| ├── .jest.config.js # Frontend
+│ ├── manage.py
+│ ├── requirements.txt
+│ ├── package.json # Frontend
+│ ├── package-lock.json # Frontend
+│ └── webpack.config.js # Frontend
+├── dev/
+│ ├── django.dockerfile
+│ ├── webpack.dockerfile
+│ └── dev.env
+├── .dockerignore
+├── .gitignore
+├── jsconfig.json
+├── CONTRIBUTING.md
+├── docker-compose.yml
+├── LICENSE
+└── README.md
+
+Overall project structure
├── frontend/
+│ ├── src/
+│ ├── assets/
+│ ├── components/
+│ ├── Apps.js
+│ └── <Components>/
+│ ├── context/
+│ ├── QualifiersContext.tsx
+│ ├── pages/
+│ ├── templates/
+│ └── index.html
+│ ├── index.js
+│ └── index.scss
+│ ├── static
+│ └── templates
+├── tests/
+├── .babelrc
+├── .jest.config.js
+├── package-lock.json
+├── package.json
+└── webpack.config.js
+
+Frontend Architecture
These diagrams show how data flows through the app: Frontend and Backend UML diagrams
+Frontend Tech Stack: React, Babel, webpack, Jest, React Testing Library, HTML, SCSS, JS, TailwindCSS
+The over ninety percent of our frontend architecture is housed in our frontend/
directory. This directory is a Django app, which is a set of files that can be ported to any Django-based application.
Since our frontend is a Django app, it takes advantage of the way Django serves its static assets. Every Django app, by default, looks to the templates/
* directory within the app for the html
template file to serve. This template usually contains <script>
and <style>
tags denoting the location of SCSS and JS files. In Django, these files are usually located inside the static/
* directory. Likewise, our frontend app store our templates and static assets within these directories.
Despite these similiarties, however, the files in these two directories should never be manipulated by a developer. These files are automatically generated by an application called webpack via configurations in webpack.config.js
and .babelrc
.
The files that should be manipulated by developers are housed within the src/
directory. Inside of here are directories for assets/
, componenents/
, pages/
, router
, and templates/
. Each of these directories contains the files which webpack reads and then bundle into output files for the static/
and template/
directories.
++*Note: The
+templates/
andstatic/
directories contain within them afrontend/
directory in order to namespace template and static files. Although this serves little purpose for our project, it is a Django convention that prevents Django from confusing thetemplates/
andstatic/
directories from the frontend app vs another app.
static/
and templates/
directories.{
+ "COPs": {
+ "UI/UX": [
+ "UI/UX_Designer",
+ "UX_Researcher",
+ "UX_Writing",
+ "UX_Practice_Lead"
+ ],
+ "Engineering": [
+ "Back_End_Developer",
+ "Front_End_Developer",
+ "Full_Stack_Developer",
+ "Engineering_Practice_Lead"
+ ],
+ "Data_Science": [
+ "Data_Scientist",
+ "Data_Analyst",
+ "Data_Engineer",
+ "Data_Science_Practice_Lead"
+ ],
+ "Project/Product_Management": [
+ "Product_Manager",
+ "Project_Manager",
+ "Business_Analyst",
+ "Product_Owner",
+ "Special_Projects_Coordinator",
+ "Product_Management_Practice_Lead"
+ ],
+ "DevOps": [
+ "Site_Reliability_Engineer",
+ "Data_Engineer",
+ "Database_Architect",
+ "Security_Engineer",
+ "DevOps_Practice_Lead"
+ ]
+ }
+ }
static
directory.docker compose run webpack npm run test
.src/
directory.├── components/
+│ ├── Basics/
+│ ├── Colors.scss
+│ └── Titles.scss
+│ ├── Buttons/
+│ ├── Button.js
+│ └── Button.scss
+│ ├── Cards/
+│ ├── Cards.js
+│ └── Cards.scss
+│ └── <Components>/
+
+A closer look at a theoretical expansion of the components directory
The components directory contains our site components. Each directory in here represents a different class of components, such as Buttons/
* or Cards/
*. Within these directories are the files necessary that creates these components. Likewise, the special Basics/
directory contains small CSS classes that are reused, but not, technically, components, such as text-size or text-colors.
...
+
+module.exports = {
+ mode: 'development',
+ entry: {
+ index: "./frontend/src/index.js"
+ },
+ output: {
+ clean: {
+ keep: '.gitkeep'
+ },
+ filename: '[name].[contenthash].js',
+ path: path.resolve(__dirname, 'frontend/static/frontend'),
+ },
+ devtool: 'inline-source-map',
+ module: {
+ rules: ...
+ },
+ optimization: {
+ moduleIds: 'deterministic',
+ runtimeChunk: 'single',
+ splitChunks: ...
+ },
+ plugins: [
+ new HtmlWebpackPlugin({
+ filename: '../../templates/frontend/index.html',
+ template: '/frontend/src/templates/index.html',
+ }),
+ ],
+ watchOptions: {
+ ignored: /node_modules/,
+ },
+}
+
+webpack.config.js (truncated)
Our webpack.config.js
file is one of the most important files to understanding how our frontend architecture comes together. Therefore, this section is dedicated to the settings that we have set for this file. Note that we do not explain all the settings, as some can be found and easily deduced from webpack's configuration and guides documentation.
index.js
imports all dependencies and files that makes up our product. Note that advanced multiple entry is possible, should we ever need it.static/
directory<script>
and <styles>
path by reading the template and outputing it with the path noted by filename. This output path follows Django's default template directory structure..gitkeep
file is there to give an empty file for git to preserve the otherwise empty directory when pushed onto GitHub. As you might have guessed, git does not push empty directories.If you have explored documentation from webpack, you might learn that the babel-loader in module > rules can accept the settings noted in .babelrc
. The reason why we separate these settings into another file is because webpack is not, in theory, the only application that makes use of these settings. Although we have no other apps that makes use of .babelrc
at the moment, this can change in the future. Therefore, this separation of files is a form of future proofing.
Our tests exists inside the tests directory with subdirectories that follows frontend/src
. There is also __mock__/
which contains code that bypasses certain tricky imports, such as svg or SCSS assets, which are not needed when testing. In order to understand how to write tests, be sure to take a look at the documentation for React Testing Library, the parent DOM Testing Library, and the support libraries jest-dom and user-event.
To run these tests, use the command docker compose run webpack npm run test
(or with test:w
for watch mode). The tests are run through jest, while the other libraries support react testing by providing functions to render DOM elements and simulate user behavior.
Note: jest-environment-jsdom
is a library that is absolutely required to link jsdom to jest. It provides the classes necessary for jest to interpret the jsdom environment. This information is listed here as it is not listed in jest's or jsdom's docs.
In addition to testing the functioning of our components, we also test the accessability of it via the library, @axe-core/react. This library prints out accessibility issues onto the browser console, providing accessibiltiy testing once the HTML has fully rendered. That said, the library is known to give both false positives and false negatives. As always reading the official documentation is best when it comes to resolving these errors.
+Sass Documentation
+React Documentation
+Webpack Documentation
+@babel/preset-react Documentation
+React Router Documentation
+Jest Documentation
+React Testing Library Documentation
+@axe-core/react Documentation
+WAI-ARIA Authoring Practices 1.1
├── .github/ # Github
+│ └── ISSUE_TEMPLATE/
+├── app/
+│ ├── config/
+│ └── settings.py
+│ ├── frontend/
+│ ├── server/
+│ ├── .babelrc
+│ ├── manage.py
+│ ├── requirements.txt
+│ ├── package.json
+│ ├── package-lock.json
+│ └── webpack.config.js
+├── dev/
+│ ├── django.dockerfile
+│ ├── webpack.dockerfile
+│ └── dev.env
+├── .dockerignore
+├── .gitignore # Github
+├── jsconfig.json
+├── CONTRIBUTING.md # Github
+├── docker-compose.yml
+├── LICENSE # Github
+└── README.md # Github
+
+Overall project structure
├── .github/
+│ └── ISSUE_TEMPLATE/
+├── .gitignore
+├── CONTRIBUTING.md
+├── LICENSE
+└── README.md/
+
+GitHub structure
This guide runs through the steps needed to create and run a local version of our project.
+If you are ever stuck or need clarification, you can contact our team members or the development lead through our Slack or email, and schedule a pair programming session with one of our developers. All of us have been through these steps, and am more than happy to help. By helping you, we can better improve our documentation and grow this project!
+Git - Windows - macOS - Linux/Unix
+Docker - Windows - macOS - Linux/Unix
+Prettier - VSCode Extension
While developing, make sure to create new branches off of the develop
branch. To checkout the develop
branch into your local repository, you can do the following:
CivicTechJobs/
, in the terminal.git remote add upstream https://github.com/hackforla/CivicTechJobs.git
- this command adds the original hackforla CivicTechJobs github repo as a remote to your local repository and names it "upstream".git fetch upstream develop
- this command fetches the develop
branch.git checkout -b develop upstream/develop
- this command creates and checks out a new branch called "develop" that tracks the upstream develop
branch.CivicTechJobs/
, in the terminal.dev/
, create a file named, dev.env
.dev.env.example
. Afterwards, you must edit the lines specified below.cd frontend
and then npm install
. When this is finished, move back to the root directory cd ..
docker compose up --watch
to run the local server.http://localhost:8000
and you should see the front page of our website!The `--watch` flag enables hot module reloads during development. This flag requires a later version of Docker Compose(2.22.0).
+If you are running into issues or getting errors running `docker compose up --watch`, please make sure you have installed the latest version of Docker and Docker Desktop on your machine.
+This section might answer some of the burning questions you have. If you cannot find it here, be sure to contact our team members or the development lead through our Slack or email.
+Make sure to turn on Docker by opening the Docker program on your desktop.
+Make sure that your terminal location is in a directory with a docker-compose.yml
file. And make sure that the file is not hidden.
This can result for several reasons, such as havin your sockets overloaded. In order to prevent this, the best thing to do is to lower the amount of sockets used when performing npm install. Change this line in docker/webpack
:
RUN npm install
to:
+RUN npm install --maxsockets=1
This should allow docker compose up
to work. Be sure to delete the addition once your image and container is set up.
This sometimes happen when npm did not install successfully. In this scenario, you need to manually install the dependencies inside the container. Generally the command to run a command inside a container is:
+docker compose run [container name] [command to run in container]
In this scenario, the full command would be:
+docker compose run webpack npm install
In this case, the index.html
file has incorrect ownership and/or permissions. To fix this, run the following command in the root directory of the CTJ repository:
sudo chown -R $USER:$USER
This will utilize superuser permissions to change the user and group ownership of all the files and directories in the current directory to the current user.
+Git Documentation
+Docker Documentation
+Frontend Architecture
+Backend Architecture
+DevOps Architecture
+GitHub Architecture
├── .github/
+│ ├── ISSUE_TEMPLATE/
+│ └── workflows/
+│ └── mkdocs-build.yml # Docs
+├── backend/
+├── dev/
+├── frontend/
+├── mkdocs/ # Docs
+│ ├── docs/
+│ └── mkdocs.yml # Docs
+├── .dockerignore
+├── .gitignore
+├── CONTRIBUTING.md
+├── docker-compose.yml
+├── docker-compose.docs.yml # Docs
+├── LICENSE
+└── README.md
+
+Overall project structure
├── docs/
+│ ├── assets/
+│ ├── css/
+│ ├── developer/
+│ ├── joining-the-team/
+│ ├── js/
+│ └── misc/
+├── index.md
+├── resources.md
+├── mkdocs.yml
+
+mkdocs directory structure
The MkDocs "sub-project" lives in the mkdocs/
folder. A development server can be run using the docker-compose.docs.yml
compose script. The mkdocs is set to automatically deploy to github pages using the mkdocs-build.yml
github action.
It is important to note that we are using Hack for LA's prebuilt docker mkdocs image for convenient setup. Please see the resources below for more information:
+This prebuilt docker image makes it easy to get a mkdocs development server running with one command, without having to install python or mkdocs dependencies on your local machine. It also includes common useful plugins that we dont have to worry about installing ourselves, and already includes the mkdocs-material
theme pre-installed.
Our project implements the HFLA mkdocs image by pulling it inside the docker-compose.docs.yml
file:
name: civic-tech-jobs-mkdocs
+
+services:
+ mkdocs:
+ container_name: mkdocs
+ image: hackforlaops/mkdocs:latest
+ command: mkdocs serve -a "0.0.0.0:8005"
+ ports:
+ - "8005:8005"
+ volumes:
+ - ./mkdocs:/app
+ develop:
+ watch:
+ - action: sync
+ path: ./mkdocs
+ target: /app
+
+Now when we run docker compose up like so:
+docker-compose -f docker-compose.docs.yml up --watch
+
+A mkdocs development server is started on http://localhost:8005
The url for the github pages site is: https://hackforla.github.io/CivicTechJobs/
(the website you are reading this on right now).
Our github repo is set to publish the docs to Github Pages using the gh-pages
branch. This setting can be configured in the project's Pages settings.
External Resources:
+ +Relevant PR and Issue:
+ +The docs are set to automatically deploy to github pages using the mkdocs-build.yml
github action. This action builds the mkdocs and saves the static files into the gh-pages
branch.
Links to the github action: Build MkDocs site (develop)
+name: Build MkDocs site (develop)
+
+on:
+ push:
+ branches:
+ - develop
+ paths:
+ - "mkdocs/**/**.md"
+ - "mkdocs/mkdocs.yml"
+ workflow_dispatch:
+
+permissions:
+ contents: write
+
+jobs:
+ deploy-docs:
+ runs-on: ubuntu-latest
+ if: github.actor != 'github-actions[bot]'
+ steps:
+ - uses: actions/checkout@v4
+ - name: Configure Git Credentials
+ run: |
+ git config user.name github-actions[bot]
+ git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+ - uses: actions/setup-python@v5
+ with:
+ python-version: 3.x
+ - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+ - uses: actions/cache@v4
+ with:
+ key: mkdocs-material-${{ env.cache_id }}
+ path: .cache
+ restore-keys: |
+ mkdocs-material-
+ - name: Install Dependencies
+ run: pip install \
+ mkdocs-material==9.1.17 \
+ mkdocs-autolinks-plugin==0.7.1
+ - name: Publish docs
+ run: |
+ cd mkdocs
+ mkdocs gh-deploy --force
+
+Workflow Overview
+name: Build MkDocs site
- The name of this workflow is "Build MkDocs site."on: push: - develop
- The workflow is triggered when there’s a push to the develop branch. (We will change this to main
later)paths: ...
- The workflow will only run if the files being pushed are Markdown files (.md
) or the mkdocs.yml
configuration file inside the mkdocs directory.workflow_dispatch:
- This allows manual triggering of the workflow via the GitHub Actions interface.permissions: contents: write
- This grants the action permission to write contents to the repository. It's needed for deploying the site, which requires pushing to the gh-pages
branch.runs-on: ubuntu-latest
- This specifies that the job will run on the latest Ubuntu environment provided by GitHub Actions.if: github.actor != 'github-actions[bot]'
- This condition ensures that the job doesn’t trigger if the GitHub Actions bot is the one making the changes. This prevents infinite loops where the action keeps triggering itself.uses: actions/checkout@v4
- This step checks out the repository code so the workflow can access the files.run: git config user.name github-actions[bot]
- Configures Git to use the github-actions[bot]
user for any commits or pushes that may happen during the deployment.git config user.email 41898282+github-actions[bot]@users.noreply.github.com
- Sets the email for the github-actions[bot] user.uses: actions/setup-python@v5
- This sets up a Python environment in the GitHub runner, which is necessary for installing and running MkDocs.Set environment variable for caching
+run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
cache_id
to the current week of the year (%V
). This value will be used as the key for caching to ensure that the cache is updated weekly.Cache dependencies
+uses: actions/cache@v4
- This step caches dependencies (to speed up future builds) in the .cache directory.with: key: mkdocs-material-${{ env.cache_id }}
- The cache key is based on the cache_id, so the cache is refreshed weekly.path: .cache
- Specifies that the cache should be stored in the .cache directory.restore-keys: mkdocs-material-
- This allows for fallback caching if an exact cache match is not found.Install Dependencies
+run: pip install mkdocs-material==9.1.17 mkdocs-autolinks-plugin==0.7.1
mkdocs-material==9.1.17
: A popular theme for MkDocs.mkdocs-autolinks-plugin==0.7.1
: A plugin that automatically creates links between pages in your documentation based on their titles.Publish Documentation
+run: cd mkdocs && mkdocs gh-deploy --force
mkdocs/
directory.mkdocs gh-deploy --force
. The --force
flag ensures that the contents of the GitHub Pages branch (gh-pages
) are overwritten with the latest deployment.This workflow automates the process of building and deploying a MkDocs site when changes are pushed to the develop branch. It does the following:
+gh-deploy
.This workflow ensures the documentation is always up to date and available on GitHub Pages whenever changes are made to relevant Markdown files or the MkDocs configuration.
+ + + + + + +The goal of this page is to document how to create and publish new changes to the CTJ documentation.
+Writing documentation into mkdocs requires some knowledge of Markdown.
+What you essentially need to know:
+.md
files located in the mkdocs/docs/
folder..md
file in the appropriate folder.mkdocs.yml
file.MkDocs provides a development server that makes it convenient to see your changes in localhost
before you deploy them to github.
For more a detailed editing guide please see the official MkDocs Tutorial
+To start the development server, simply go to the root of your project in the terminal and run the following command:
+docker-compose -f docker-compose.docs.yml up --watch
+
+Next, go to http://localhost:8005
in your browser.
Now when you save new changes to the .md
files, the respective page will automatically be updated in the browser.
When you are done editing, the next step is to deploy your changes.
+When you are satisfied with your edits, make a pull request so that they can be reviewed.
+Once the pull request is approved and merged into develop
, the changes will be automatically deployed to the official CivicTechJobs documentation site (the site you are reading this page in right now). That's it!
If anything goes wrong, you can investigate the workflow in the project's github actions page
+Note: At the moment, the docs are set to deploy from the develop
branch, using the github action located in mkdocs-build.yml
. This means that whenever a file is changed inside the mkdocs/
directory, and is merged into the develop
branch on github, the changes will be automatically deployed to the official site hosted on github pages. In the near future we will set it to deploy from the main
branch.
Check out our MkDocs Architecture page for more details on how it all fits together.
+To sum it all up, you can make changes in 4 easy steps:
+docker-compose -f docker-compose.docs.yml up --watch
.md
files and observe them in http://localhost:8005
develop
branchWe are using mkdocs to handle documentation.
+Developers should document their architectural and coding decisions, so that other team members can easily reference these docs whenever they are lost or confused or new to the project.
+MkDocs is a static site generator that is designed specifically for building project documentation. It allows you to write documentation using Markdown, a lightweight markup language that's easy to use, and generates a clean, professional website that can be hosted on our project's GitHub Pages.
+Please see MkDocs - How to Edit for instructions on how to make changes to the CTJ documentation and publish new docs.
+Code functionality
+Setup Instructions
+Common Use Cases
+Troubleshooting
+Code Examples
+API Documentation
+CivicTechJobs will be a site to find open volunteer positions for projects at hackforla.
+CivicTechJobs will be a platform to help prospective volunteers find interdisciplinary projects that will be useful for their career development while contributing to positive civic impact, and also a CMS (Content Mgmt System) for Hack for LA projects to be able to list their open roles.
+To match the right volunteers with the right projects at hackforla.
+Yes, through CoP GitHub pages. However, the process is cumbersome and involves multiple steps to match the candidate with the right role.
+Read more about what lead up to us developing this project, at our History page.
+We would like to streamline the process so that Product Managers can post the open oppotunities within their team efficiently, but most importantly a volunteer is able to find the right match with a project based on their skills, and aspirations.
+You can access our project one sheet here.
+To take a look at some of our key resources:
+ + + + + + + +DRAFT NOT YET FILLED OUT
+Review existing copy on the CivicTechJobs.
+Review the Figma for pages that are not yet published.
+Review the Project Board and identify an actionable backlog item.
+Communicate with PM your interest in being assigned a task.
+DRAFT NOT YET FILLED OUT
+Read the Readme.
+Review the Project Board and identify an actionable backlog item. We are working to resolve some database architecture issues and are not onboarding new data scientist at this time.
+Communicate with the PM on your interest in being assigned a task.
+DRAFT NOT YET FILLED OUT
+Welcome to the Civic Tech Jobs team! This guide will help get you up to speed on what you need to know to get started as a project team member.
+If you have not read the Guide for New Volunteers, please do so.
+Click the link that applies to you to find a sequence of immediate action steps:
+ + + + + + + +Title III of the Americans with Disabilities Act (ADA) requires that all sites be accessible to people with disabilities. The World Wide Web (W3C) Consortium's Web Content Accessibility Guidelines (WCAG) 2.0 Level AA function as the current legal standard for site accessibility.
+Get acquainted with accessibility: https://www.ada.gov/pcatoolkit/chap5toolkit.htm
+ + + + + + +DRAFT NOT YET FILLED OUT
+Get an overview of the project from the Wiki.
+Review the Project Board.
+Chat with a [INSERT PROJECT NAME HERE] PM to discuss your interest and background.
+DRAFT NOT YET FILLED OUT
+Each of the resources below can be considered a work-in-progress. These resources will evolve and adapt as the team and team needs change. Feel free to open an issue with a link to whichever resource needs improvement and a description of the suggested change.
+Learn how we setup our GitHub Kanban boards and please comment if there is anything in the document that is unclear.
+This Software Development Lifecycle Diagram is a sample of what the process is generally like at Hack for LA and each project is different.
+Review our OKRS.
+Communicate with other product team members and leadership to discuss project priorities and strategic direction.
+Review the Project Board and the Product Management issues available on that board to identify an actionable backlog item.
+Review Hack for LA Product Management Templates.
+Review the UI/UX issues on the Project Management Board and identify an actionable backlog item.
+Communicate with PM your interest in being assigned a task.
+Ask your lead to invite you to the Civic Tech Jobs figma workspace
+This is a generic software development lifecycle diagram for Hack for LA. We would like to talk to you about how this project is different.
+Read about WCAG 2.0 accessibility standards.
+DRAFT NOT YET FILLED OUT
+Read the development Readme and the CONTRIBUTING.md file set up your development environment.
+Review the project board by the type of issue you are looking for. The Frontend Coding Project Board or the Backend Coding Project Board. Or you can check out the entire project board here.
+Communicate with the PM about your interest in being assigned a task.
+Your first commit will likely be an issue labeled good first issue. Check the board for those issues. Don't worry if you don't see anything now, we are working on it.
+Read about WCAG 2.0 accessibility standards and set up third-party tools for compliance testing.
+Review notes on security updates.
+Site architecture document is coming soon.
+DRAFT NOT YET FILLED OUT
+There are more than 100 accessibility testing tools. Figuring out which ones to use can be a black hole. For guidance we recommend this article: Which accessibility testing tool should you use?
+The author recommends using the tools in the following order fixing as you go along, since no one tool catches all the relevant issues
+aXe +SiteImprove +Tenon +WAVE +Lighthouse
+But if you want to test your site with other tools, here is a bigger list
+ + + + + + +DRAFT NOT YET FILLED OUT
+When we have a shiny glossary it will come here.
++Term | +Alternate terms | +Official Link | +Description |
+ | + | ++ | +|
+ | + | ++ | ++ |
How Hack for LA evolved from in person onboarding to remote, and the iterative approach that we have taken to arrive at the need for a dedicated interface to list volunteer opportunities.
+Hack for LA practiced in person recruiting on onboarding nights. It had its own benefits, like each volunteer felt valued and had agency
+The team later moved on to a new process where the open roles on each team were posted on the Hack For LA site. This led to:
+Hack for LA moved to a new model where all new volunteer attend onboarding and then join a communities of practice (CoP) and no open roles are posted on the hackforla.org site. These CoPs have volunteer opportunity boards so that when project leads recruit, they can go to a larger group of people who are more likely to be a good fit for the role available. Also CoP leads can help provide coaching if someone is unsure of if they are a good fit. Listings at CoP allow the org to determine if the project is actually ready to receive volunteers.
+The Hack for LA organization team has now green lighted a project to create a dedicated job board page where volunteers can search and find volunteer opportunities that match their goal and aspirations while still maintaining the involvement of onboarding and CoPs.
+ + + + + + +This page has links and details such as links to a spreadsheet with our research, etc. and what order we did things in. But less narrative and mostly links
+ + + + + + +# [Name of Research]
+
+## Research Date:
+
+## Current Status
+
+## Overview Issue #:
+
+## Outstanding task items
+
+## Assets
+
+### Research Plan (including Audience Identification documentation)
+
+### Scripts
+
+### Interview recordings & Transcripts
+
+### Synthesis (Miro or Figjam)
+
+### Presentation of Findings
+
+### Action Items Spreadsheet
+
+
+
+
+
+
+
+ This project subscribes to GitHub's automated security alerting service. Occasionally the repository home page may have a yellow banner saying "We have found a potential security vulnerability in one of your dependencies" and a link to view the security alert. If you see this, please check our issues list to see if anyone has added an issue for fixing this. If not, please create an issue for this problem. If you feel up to it, please assign the issue to yourself and try to fix it. As with any issue, once you have fixed it on your fork of the repository, push the fixes to your fork and then open a pull request to merge this fix into the main repository.
+GitHub's "dependabot" may try to generate an automated pull request to fix this issue. Please do not accept this pull request without verifying that it works by applying the update on your local copy of the site.
+ + + + + + +Name | +Role | +
---|---|
Joyce Guo | +Product Manager | +
Sabrina Heasley | +Product Manager | +
Salima Yacoubi Soussane | +Product Manager | +
Bitian Zhang | +Full Stack Developer | +
Matt Pereira | +Full Stack Developer | +
Will Gillis | +Full Stack Developer | +
Sarah Sanger | +Software Developer | +
Benny Van | +Software Developer | +
Jen Chung | +UX/UI Designer Lead | +
Tin Wei, Chung | +UX/UI Designer | +
Lu Feng | +UX/UI Designer | +
Gabriel Vicencio | +UX/UI Designer | +
Melinda Sukosd | +UX Researcher Lead | +
Leah Ellis | +UX Researcher | +
Jenn Wu | +UX Researcher | +
Nga Do | +UX Researcher | +
More resources to be added as project progresses:
+#civictechjobs
slack channel (in the Hack For LA organization slack)#civictechjobs-dev
channelCivicTechJobs will be a site to find open volunteer positions for projects at hackforla.
"},{"location":"#introduction-to-the-project","title":"Introduction To The Project","text":""},{"location":"#what-is-civictechjobsorg","title":"What is Civictechjobs.org?","text":"CivicTechJobs will be a platform to help prospective volunteers find interdisciplinary projects that will be useful for their career development while contributing to positive civic impact, and also a CMS (Content Mgmt System) for Hack for LA projects to be able to list their open roles.
"},{"location":"#why-do-it","title":"Why do it?","text":"To match the right volunteers with the right projects at hackforla.
"},{"location":"#hasnt-it-been-done-already","title":"Hasn't it been done already?","text":"Yes, through CoP GitHub pages. However, the process is cumbersome and involves multiple steps to match the candidate with the right role.
Read more about what lead up to us developing this project, at our History page.
"},{"location":"#so-how-is-this-different","title":"So how is this different?","text":"We would like to streamline the process so that Product Managers can post the open oppotunities within their team efficiently, but most importantly a volunteer is able to find the right match with a project based on their skills, and aspirations.
"},{"location":"#guiding-objectives","title":"Guiding Objectives","text":""},{"location":"#what-are-our-guiding-objectives","title":"What are our guiding objectives?","text":"You can access our project one sheet here.
"},{"location":"#key-resources","title":"Key Resources","text":"To take a look at some of our key resources:
More resources to be added as project progresses:
"},{"location":"resources/#core-start-here","title":"Core - Start here","text":"#civictechjobs
slack channel (in the Hack For LA organization slack)#civictechjobs-dev
channel\u251c\u2500\u2500 .github/\n\u2502 \u2514\u2500\u2500 ISSUE_TEMPLATE/\n\u251c\u2500\u2500 app/ # Backend\n\u2502 \u251c\u2500\u2500 config/ # Backend\n\u2502 \u2514\u2500\u2500 settings.py\n\u2502 \u251c\u2500\u2500 frontend/ # Backend\n\u2502 \u251c\u2500\u2500 server/ # Backend\n\u2502 \u251c\u2500\u2500 .babelrc\n\u2502 \u251c\u2500\u2500 manage.py\n\u2502 \u251c\u2500\u2500 requirements.txt # Backend\n\u2502 \u251c\u2500\u2500 package.json\n\u2502 \u251c\u2500\u2500 package-lock.json\n\u2502 \u2514\u2500\u2500 webpack.config.js\n\u251c\u2500\u2500 dev/\n\u2502 \u251c\u2500\u2500 django.dockerfile\n\u2502 \u251c\u2500\u2500 webpack.dockerfile\n\u2502 \u2514\u2500\u2500 dev.env\n\u251c\u2500\u2500 .dockerignore\n\u251c\u2500\u2500 .gitignore\n\u251c\u2500\u2500 jsconfig.json\n\u251c\u2500\u2500 CONTRIBUTING.md\n\u251c\u2500\u2500 docker-compose.yml\n\u251c\u2500\u2500 LICENSE\n\u2514\u2500\u2500 README.md\n
Overall project structure
\u251c\u2500\u2500 config/\n\u2502 \u251c\u2500\u2500 <Django Project Files>\n\u251c\u2500\u2500 frontend/\n\u2502 \u2514\u2500\u2500 <Django App Files>\n\u251c\u2500\u2500 server/\n\u2502 \u251c\u2500\u2500 <Django App Files>\n\u2502 \u251c\u2500\u2500\u2500 <RESTFramework Files>\n| \u2514\u2500\u2500 templates\n\u251c\u2500\u2500 manage.py\n\u2514\u2500\u2500 requirements.txt\n
Backend Architecture
These diagrams show how data flows through the app: Frontend and Backend UML diagrams
"},{"location":"developer/backend/#summary","title":"Summary","text":"Backend Tech Stack: Django, DjangoRESTFramework
The backend architecture is consists the the Django config/
project, and the frontend/
and server/
Django apps. In addition to serving as part of our backend, the frontend/
directory also serves our frontend architecture. More about the frontend/
directory as it relates our frontend architecture can be found in our guide on Frontend Architecture.
frontend/
and server/
. Within these directories are the default <Django App Files>
that are created with every app as well as <RESTFramework Files>
.serializers.py
, these files are additional files that support Django via the DjangoRestFramework library.package.json
.\u251c\u2500\u2500 migrations/\n\u2502 \u2514\u2500\u2500 __init__.py\n\u251c\u2500\u2500 __init__.py\n\u251c\u2500\u2500 admin.py\n\u251c\u2500\u2500 apps.py\n\u251c\u2500\u2500 models.py\n\u251c\u2500\u2500 tests.py\n\u251c\u2500\u2500 urls.py\n\u2514\u2500\u2500 views.py\n
Files generated by Django when creating a new Django app
These files uses DjangoRestFramework in order to quickly create an API. The most often editted files here are models.py
, urls.py
, and views.py
. The models define the schema for our database tables. Once the models are made, they are router to views.py where the data is transformed and exposed to our API. It is in views where we create handlers to manage REST operations.
Please refer to Django's documentation for more information.
"},{"location":"developer/backend/#django-rest-framework-files","title":"Django REST Framework Files","text":"\u251c\u2500\u2500 serializers.py\n
RESTFramework files used to create a Django REST API
Serializers turn the data from the database into a Python-readable form.
Please refer to DjangoRESTFramework's documentation for more information.
"},{"location":"developer/backend/#additional-resources","title":"Additional Resources","text":"Django Documentation DjangoRestFramework Documentation
"},{"location":"developer/design-system/","title":"Design System Helper","text":"This guide is the developer documentation for the CivicTechJobs Design System (CTJ-DS). Inside is not only an overview of our components, but also usage tips, and strategies to translate Figma designs into components for flexible, dynamic web pages.
"},{"location":"developer/design-system/#concepts","title":"Concepts","text":"To understand our Design System, these are some overarching concepts to keep in mind when working with the DS.
"},{"location":"developer/design-system/#implementing-from-figma-to-frontend-development","title":"Implementing from Figma to Frontend Development","text":"UI designers specialize in turning project requirements into graphical interfaces that fits project requirements. Designers, however, are not coders. As a result, here are some development-related aspects of componentization that designers do not consider:
Because of these factors, the way a prototype is built on Figma does not necessarily translate 1:1 to how the designs should be build as code. For example, Figma designs does not use SCSS mixins to simplify code or percentages as units of size.
Likewise, we must contend with the fact that Figma designs are static screens tied to very specific viewport sizes. As developers we need to recreate the Figma designs while also considering the intent behind a design.
As a developer, we need to effectively communicate with designers at multiple stage of the Figma design process. This means providing recommendations or alternatives that are simpler and easier for the developer to implement and maintain.
At CivicTechJobs, designers use two standard viewport widths when creating our UIs: 1440px for desktop and 375px for mobile. The appearance of the UI beyond these two sizes are determined by us, as developers, as we componentize the Figma designs. Do note though that our screen size of interest changes depending on the stage of our project. Right now, our current size of interest is:
1025px and up (or, laptop and up)\n
"},{"location":"developer/design-system/#scalable-and-responsive-components","title":"Scalable and Responsive Components","text":"When creating or using components, it is good to keep in mind the differences between a scalable component and responsive component.
A scalable component:
These columns show scalable behavior. The columns smoothly shrink and grow with the screen size.
A responsive component:
These buttons show responsive behavior. The buttons do not change until the screen reaches a certain breakpoint.
Scalability and responsiveness are not mutually exclusive. A web page can contain both scalable and responsive components. As a matter of fact, a single component can be both responsive and scalable.
This card shows both scalable and responsive behavior. The width smoothly change with the screen size, but drastically changes at our max small tablet breakpoint.
Only by combining both scalability and responsiveness in our design, can we create a high-quality site. When translating from Figma to code, most of the time, the work is in deciding what part of the Figma design should scale, and what part should be responsive. As a rule of thumb, when designing the transition from the desktop to mobile Figma, scale down empty space and margins, and responsively shrink buttons and text.
"},{"location":"developer/design-system/#proptype-as-documentation","title":"PropType as Documentation","text":"As a small project, React recommends the use of PropTypes as our type checking library.
By using PropTypes, we have an easy way to look up hints on how to use our components.
Button.propTypes = {\n addClass: PropTypes.string,\n color: PropTypes.oneOf([\"primary\", \"primary-dark\"]),\n disabled: PropTypes.bool,\n href: PropTypes.string,\n length: PropTypes.oneOf([\"\", \"long\"]),\n onClick: PropTypes.func,\n size: PropTypes.oneOf([\"sm\", \"md\", \"lg\", \"icon\"]),\n target: PropTypes.oneOf([\n \"_blank\",\n \"_self\",\n \"_parent\",\n \"_top\",\n PropTypes.string,\n ]),\n};\n
For this <Button> component, PropTypes provide clues on the component's props. From these hints, a developer can guess that a small, long button would be declared as <Button size=\"sm\" length=\"long\">
Because comprehensive documentation is difficult for a small team to maintain, we rely on PropTypes and cleanly written code to provide clues on how to use each component. We recommend new developers take time to play with the components in components/
to fully understand how to utilize them. You can use the /demo web endpoint and Demo.js when developing to play around with our components.
While we can use pure CSS as our styling sheet, using SCSS with React components allows us to standardize our components in a powerful way. Componentization allows:
Because of these benefits, we use a component-first approach to developing web pages. Please componentize as much as possible and use them to build high-quality web pages!
As a note, the DS is put together based on industry trends and practices. If you have ever explored Bootstrap, MUI, or Atlassian Design System, you will see many similarities between their components and ours.
"},{"location":"developer/design-system/#mixins-and-classes","title":"Mixins and Classes","text":"Most of our styles have a class and mixin equivalent. The class, for the most part, is created from just declaring the mixin inside the class.
@mixin hidden {\n display: none;\n}\n\n.hidden {\n @include hidden;\n}\n
Above is the hidden mixin definition. Below is the hidden mixin declaration as part of the .hidden class.
These are both provided to suit different use cases. For example, the class version is best suited for declaring inside of React components or HTML elements as part of the addClass
prop or className
attribute. On the other hand, the mixin version is best used when adding it to your own custom style, such as with media queries.
.my-own-custom-class {\n @include breakpoint-media-max(\"smtablet\") {\n @include hidden; // Do this\n @extend .hidden; // Do not do this, will break\n\n @include col-size(6); // Do this\n @extend .col-6; // Do not do this, will break\n }\n}\n
Please use the mixin version when you want your own custom style to inherit from an existing style!
"},{"location":"developer/design-system/#layout-and-columns","title":"Layout and Columns","text":"As with most design systems, we use a standard 12-column system to subdivide our layouts. Each column, without spacing, is worth *8.33% of its container's width**. This means that columns are, by default, scalable.
To use of our column classes, first declare a parent container with the .flex-container
class. Then use col-*
classes in each children, replacing the *
with the number for the column size.
We need to use a parent .flex-container
with col-*
classes to subdivide the UI.
Our 12-column system can be used in conjunction with .row
and nested .col-*
to further subdivide the UI, and create more complex layouts.
With .flex-container
, .row
, and .col-*
, we can create complex layouts that fit our purposes.
\"99% of the time, you'll want to reclaim space from padding, margins, or empty space as screen size shrinks.\"
The spacing utilities are classified by attributes and size.
Table of Spacing Attributes
Spacing attribute (margins) Meaning | Spacing attribute (padding) Meaning m all margins | p all paddings mt margin-top | pt padding-top mr margin-right | pr padding-right mb margin-bottom | pb padding-bottom ml margin-left | pl padding-left mx margin-left and -right | px padding-left and -right my margin-top and -bottom | py padding-top and -bottomTable of Spacing Sizes
Spacing size Actual size (px) 0 0px 1 8px 2 16px 3 24px 4 32px 5 40pxTables showing the different way we classifies our spacing utilities. As an example, .px-4
sets the left and right padding as 32px.
Because our DS is based on a 12-column system, spacing utilities are made such that adding them on would not alter the 12-column system. For that reason, it is optimal to use the spacing utilities whenever possible over setting custom margins or padding.
Add margins responsibly. Try to use the spacing utilities over creating custom margin classes.
As an example, if Figma indicates a 10px left margin, use either .ml-1
or .ml-2
. Other times, however, Figma designs show spacing that falls outside of our size range. In this scenario, rather than set a specific margin, try to use centering instead, as large spaces are usually not a result of spacing, but of centering.
By being smart about the way we include spacing, we ensure scalability and reduce the maintenance cost of our code.
"},{"location":"developer/design-system/#responsive-mixins","title":"Responsive Mixins","text":"\"When using responsive mixins, order matters! Always declare them from big to small.\"
Several of our components have *-responsive
mixins at the end of the .scss
file. These act as helpers to quickly create responsiveness into our components, keeping our code simple to understand.
These mixins always use max-width in its media query (as we use a desktop-first approach), so order matters! To use them properly, specify a default* and declare screen size from largest to smallest:
DO: specify a default on top and declare *-responsive
mixins from large to small screen sizes.
DON'T: declare *-responsive
mixins without a default on top or from a smaller to larger screen size.
SVG assets are read into our codebase as React components (or inline SVG) or data-urls.
As React components:
As Data-urls:
img
tags, to allow quick width/length adjustments?url
qualifiers// COP Icons\nimport CopIconData from \"./svgs/cop-icon-datascience.svg\";\nimport CopIconEngineering from \"./svgs/cop-icon-engineering.svg\";\nimport CopIconOps from \"./svgs/cop-icon-ops.svg\";\nimport CopIconProduct from \"./svgs/cop-icon-product.svg\";\nimport CopIconUiux from \"./svgs/cop-icon-uiux.svg\";\n\nimport copIconData from \"./svgs/cop-icon-datascience.svg?url\";\nimport copIconEngineering from \"./svgs/cop-icon-engineering.svg?url\";\nimport copIconOps from \"./svgs/cop-icon-ops.svg?url\";\nimport copIconProduct from \"./svgs/cop-icon-product.svg?url\";\nimport copIconUiux from \"./svgs/cop-icon-uiux.svg?url\";\n
The top icons are imported from the image file as SVG components (or inline SVG). The bottom icons are the same file imported as data-urls. Notice how the latter import file adds \"?url\".
When using our SVG assets make sure to use the best import for the job. In some cases, however, neither of these imports are optimal to use. For example the SVG itself might be incorrectly formatted.
This SVG contains extra spaces, especially on the bottom. This image is impossible to center correctly without adding unnecessary margins.
In this case, rather than calculating some difficult to maintain, complex spacing, simply request the design team to provide a better SVG or edit the SVG yourself and send a copy to the design team.
"},{"location":"developer/design-system/#troubleshooting-errors","title":"Troubleshooting Errors","text":""},{"location":"developer/design-system/#you-may-not-extend-selectors-across-media-queries","title":"You may not @extend selectors across media queries.","text":"This happens when @extend is used inside of media queries. An example using our DS,
.header-logo-desktop {\n @include breakpoint-media-max(\"smtablet\") {\n @extend .hidden;\n }\n}\n
Using @extend inside of a media query will result in an error. Instead, use a mixin declaration with @include instead. Most classes in the DS include an equivalent mixin for this specific purpose.
.header-logo-desktop {\n @include breakpoint-media-max(\"smtablet\") {\n @include hidden;\n }\n}\n
This works because it declares a mixin rather than extend the class!
To avoid these errors, it is encouraged to use the mixin rather than the class version of a specific style for inheritance whenever possible!
For more information visit this documentation and this Stack Overflow question.
"},{"location":"developer/design-system/#resources","title":"Resources","text":"Atomic Design Atlassian Design System Bootstrap Material-UI
Note: If embeds are out-of-date, and you have no access to the originals, please fork and replace them through CodeSandbox!
CodeSandbox
"},{"location":"developer/development-culture/","title":"Development Culture","text":"At CivicTechJobs, the developers of our team have 3 key tasks:
This guide will discuss how each of these work at CivicTechJobs. If you have any questions be sure to let us know! We strive to create an inclusive space for developers to learn and achieve their goals.
"},{"location":"developer/development-culture/#make-issues","title":"Make Issues","text":"To make an issue, follow this guide from GitHub, or take a look at this section of the CONTRIBUTING.md.
At CivicTechJobs, updating the project starts with creating an issue outlining the situation and changes needed to resolve the situation. When writing an issue, a good rule of thumb is to write as if another developer would be the one to work on the issue. Therefore, being thorough is better than brief. Some good guidelines to follow:
After writing out the issue, be sure to add labels. At minimum, we need three labels, one each from the \"size\", \"role\" and \"feature/p-feature\" series. In most cases, you should not create your own label. If you are unsure what labels to place, it is okay to leave it be, as another team member will help you when they notice the issue lacks certain labels.
Once an issue is created, and placed in the Project Management project board, the developer is mostly done with the issue. If the issue contains a dependency, it will move into the \"Ice Box\" column via GitHub automation, or \"New Issue Approval\", otherwise.
On rare occasions, a project manager, or other team members, might ping you with questions on the issue. Perhaps the team member did not understand the jargon, or the instructions were unclear. In that case, read their concerns carefully and either answer with a comment, or edit the original issue. Eventually, the issue will be approved, prioritized, and released into the \"Prioritized Backlog\" column, where developers can work on it.
"},{"location":"developer/development-culture/#resolve-issues","title":"Resolve Issues","text":"To resolve an issue, take a look at this section of the CONTRIBUTING.md.
When choosing an issue to work on from the \"Prioritized Backlog\" column, it is good to note the \"role\" and \"size\" label. This signals the expertise required and time commitment needed to resolve the issue. As a rule of thumb, a smaller issue should take a week, and a larger issue, two or three weeks. This should give you a good idea on what issues is best for you to take at the moment. If you are completely new, we recommend taking smaller issues to understand your limits before pushing them further. That said, you are free to work on whatever you want.
On occasion, when an issue is being worked on for an inordinate amount of time, the team might request an update on your progress. When giving your progress, it is courteous to give an ETA on the issue, and evaluate on your ability to resolve the issue in a reasonable timeframe. If an issue is taking far too long, it might be wise to abandon the issue and work on something that might bring more value to you and the team.
Also, one final note: Do not contact the team via email or Slack to review your pull request unless it as been 72 hours since it was opened! The team will occasionally comb for pull requests and review them. If you want to move on to another issue, consider reviewing another developer's pull request (if you are part of the team), contribute to other open source projects, or ask the team for additional tasks.
Most issues can be divided into two broad types: frontend issues, and backend issues.
"},{"location":"developer/development-culture/#frontend-issues","title":"Frontend issues","text":"When working on frontend issues, there will usually be a link to the Figma design. Figma often contains multiple prototypes and future prototypes. When looking for our current design, go to the bottom right corner and look for a pink rectangle. Anything within that represents our most up-to-date design. Use that as a reference for your frontend issues. If the pink rectangle is not there, please request the UI design team to put a pink rectangle on the latest approved design.
On rare circumstances, designs can change in the middle of work. This is something that happens as part of development, but will often be telegraphed during meetings. If a design change, you are free to reassess and abandon your current issue, or code pragmatically to ensure your work would not need a massive overhaul.
"},{"location":"developer/development-culture/#backend-issues","title":"Backend issues","text":"To review code, please take a look at this GitHub documentation, and this portion of our CONTRIBUTING.md.
Code that should be reviewed is found in the pull request tab. These are issues that require someone to look over for several criteria:
When code meets all three criteria, it can then be merged and made a part of the site. Otherwise, the review should indicate changes that needs to be made.
As an advanced project, CivicTechJobs have certain expectations for our developers. One of these is that issues of size 1 or 2 is small enough that we \"pre-review\" them. This means that we are confident that the developer can resolve these issues without review. Therefore, these issues can be merged directly into our codebase upon resolution. That said, it is still fine to request the team to review your code if feedback is desired.
Important: Although issues can be pre-reviewed, do not make a habit of merging without making a pull request. There will be times when you performed an accidental merge, which could be a pain to fix on the command-line.
As one final note, code can be merged solely on one approved review but it is fine to request more reviewers or ask for the team to review it during a developer meeting.
"},{"location":"developer/devops/","title":"DevOps Architecture","text":"\u251c\u2500\u2500 .github/\n\u2502 \u2514\u2500\u2500 ISSUE_TEMPLATE/\n\u251c\u2500\u2500 app/\n\u2502 \u251c\u2500\u2500 config/\n\u2502 \u2514\u2500\u2500 settings.py\n\u2502 \u251c\u2500\u2500 frontend/\n\u2502 \u251c\u2500\u2500 server/\n\u2502 \u251c\u2500\u2500 .babelrc\n\u2502 \u251c\u2500\u2500 manage.py\n\u2502 \u251c\u2500\u2500 requirements.txt\n\u2502 \u251c\u2500\u2500 package.json\n\u2502 \u251c\u2500\u2500 package-lock.json\n\u2502 \u2514\u2500\u2500 webpack.config.js\n\u251c\u2500\u2500 dev/ # DevOps\n\u2502 \u251c\u2500\u2500 django.dockerfile\n\u2502 \u251c\u2500\u2500 webpack.dockerfile\n\u2502 \u2514\u2500\u2500 dev.env\n\u251c\u2500\u2500 .dockerignore # DevOps\n\u251c\u2500\u2500 .gitignore\n\u251c\u2500\u2500 jsconfig.json\n\u251c\u2500\u2500 CONTRIBUTING.md\n\u251c\u2500\u2500 docker-compose.yml # DevOps\n\u251c\u2500\u2500 LICENSE\n\u2514\u2500\u2500 README.md\n
Overall project structure
\u251c\u2500\u2500 dev/\n\u2502 \u251c\u2500\u2500 django.dockerfile\n\u2502 \u251c\u2500\u2500 webpack.dockerfile\n\u2502 \u2514\u2500\u2500 dev.env.example\n\u251c\u2500\u2500 .dockerignore\n\u251c\u2500\u2500 docker-compose.yml\n\u251c\u2500\u2500 alias-config.txt\n\u2514\u2500\u2500 alias.sh\n
DevOps Architecture
"},{"location":"developer/devops/#summary","title":"Summary","text":"DevOps Tech Stack: Docker, Gunicorn, Nginx, PostgreSQL, test
Our devops files can be thought of as a set of files needed to create an exact replica of our environments for our developers. Although the overall structure appears deceptively basic, it only represents a fraction of our devops files. Several of our files, such as the ones that construct our staging environment, contains sensitive information, and as such as not placed in our public repository. For most frontend and backend work, there is never a need to access these files.
"},{"location":"developer/devops/#note-on-the-rare-occasions-that-there-is-a-need-to-access-the-sensitive-files-for-environments-other-than-development-please-consult-the-development-lead-of-the-project-they-will-know-exactly-what-files-you-need-and-what-permissions-you-need-to-access-them","title":"*Note: On the rare occasions that there is a need to access the sensitive files for environments other than development, please consult the development lead of the project. They will know exactly what files you need, and what permissions you need to access them.","text":""},{"location":"developer/devops/#overview-of-directories-and-files","title":"Overview of Directories and Files","text":"django.dockerfile
contains information for our Django server setup. webpack.dockerfile
contains information to start our webpack watch plugin. dev.env.example
is an example of the env file needed to configure our dev environment.alias-config.txt
Docker is a platform that allows packaging and virtualizing applications within a container. This gives developers the powerful ability to collaborate in a stable, synchonized environment, and deploying web applications with the greatest of ease. We will not be going too much into Docker here, but we will explain in greater depth some of the Docker configurations we have made.
"},{"location":"developer/devops/#docker-composeyml","title":"docker-compose.yml
","text":"This file contains configuration directions for docker compose. It consists of three services: pgdb (our database), webpack (our webpack bundler), and django (our django server). The webpack and django service relies in separate dockerfiles, located in the dev
directory to build the container. This separation of dockerfiles enable each container to be build with its own set of dependencies. It also makes rebuilding the container simple when dependencies are migrated to a newer version.
For those of you used to creating applications without Docker, most would run webpack and django in separate terminals, so that they can both run at the same time. For the purposes of brevity, the different services can be considered to be Docker's way of running separate terminals.
One will also notice that the Django command uses a placeholder server name, 0.0.0.0:8000. This placeholder is important, since Docker creates an isolated environment. As a result, servers that are run in Docker does not recognize a browser from outside of that environment. Without this server name, localhost:8000 will not reach the server, as the server would recognize your browser as coming from a foreign machine. Therefore, all warnings related to 0.0.0.0, should they pop-up, should be ignored.
"},{"location":"developer/devops/#dockerfile","title":"*.dockerfile
","text":"Dockerfiles are files that define how a container is built. Although containerization is a deep concept, to put it briefly, you can think of containers as separate \"mini-computers\", each programmed to do one thing. Some containers, such as our pgdb
container does not require a dockerfile to configure it, as it works out of the box. On the otherhand, our webpack
and django
containers need dockerfile to built out the files we need to run it effectively.
FROM node:latest\n\nWORKDIR /code\n\n\n# install app dependencies\nCOPY ./package.json ./\nCOPY ./package-lock.json ./\nRUN npm install\n\n\n# add app\nCOPY . .\n
Sample dockerfile that copies the package.json from a project and installs all dependencies.
Dockerfiles are usually named as just dockerfile
, as that is the default name that docker looks for when constructing our builds. Since our project requires multiple dockerfiles, we name them with .dockerfile
extensions, a convention that allows VSCode to detect dockerfiles and use appropriate syntax highlighting.
Do note that docker and dockerfiles can be fickle to work with, especially on old devices. Further down this documentation are various tips and commands that can be used with docker to help debug your code. But as always, consulting official documentation is the best way to get accurate, up-to-date information.
"},{"location":"developer/devops/#environments","title":"Environments","text":""},{"location":"developer/devops/#development","title":"Development","text":"Our development environment is entirely defined by our docker-compose.yml
, and the files inside of dev/
. More information about those files can be found above.
Of note, however, is the dev.env.example file. This file is only a sample, but lists out all the environmental variables needed to run our site. While most of them are prefilled, some uses <>
to indicate placeholders, which must be filled in by the developer.
More information on our staging files can be found with our staging files. To access this information, please ask for the required permissions from the development lead.
"},{"location":"developer/devops/#useful-commands","title":"Useful Commands","text":"docker compose down -v\n
Useful to completely remove a container and related volumes. This is helpful when fiddling with database settings, which often breaks the database. This command allows the container to be restarted fresh.
docker compose -f <filename> <docker command>\n
Use this to specify an alternate docker-compose file to run your commands, such as docker-compose-other.yml. This is useful if you want to test out docker for yourself.
docker compose run <container> <command>\n
This is useful to run one time commands inside your container. Some good commands to run are:
docker exec -it <container> sh\n
Use this to do heavier debugging inside of your container. What this does is open the shell inside of the container's \"mini-computer\". This allows you to explore the files inside the container to see if it matches what you would expect after building is finished. This command only works when a container is running, so use docker compose run -d
to run your container in the background beforehand.
docker compose build --progress=plain\n
Sometimes when a build is happening, the logs are too opaque to debug if a step goes wrong. This commands makes the logs a bit more verbose so that you might have an easier time debugging.
"},{"location":"developer/devops/#alias-shell-script","title":"Alias Shell Script","text":"For convenience, we have created a shell script that allows for longer commands to be executed with less typing. The script is capable of executing any of the commands listed in alias-config.txt
without having to type out the entire command.
alias.sh
","text":"To use this script, run bash alias.sh $arg
or ./alias.sh $arg
where $arg
is the alias of the command you wish to execute. For example, try running bash alias.sh test
.
alias-config.txt
","text":"This file contains many of the important commands you will need when developing for this project. Note that each command starts with a single word followed by a :
and then a command. You must follow this pattern when adding additional commands to the file. Please note that any docker run
commands must use the -T
flag to allocate a pusedo-TTY or the command will not work.
Docker Documentation
"},{"location":"developer/frontend/","title":"Frontend Architecture","text":"\u251c\u2500\u2500 .github/\n\u2502 \u2514\u2500\u2500 ISSUE_TEMPLATE/\n\u251c\u2500\u2500 app/\n\u2502 \u251c\u2500\u2500 config/\n\u2502 \u2514\u2500\u2500 settings.py\n\u2502 \u251c\u2500\u2500 frontend/ # Frontend\n\u2502 \u251c\u2500\u2500 server/\n| \u251c\u2500\u2500 tests/ # Frontend\n| \u251c\u2500\u2500 .babelrc # Frontend\n| \u251c\u2500\u2500 .jest.config.js # Frontend\n\u2502 \u251c\u2500\u2500 manage.py\n\u2502 \u251c\u2500\u2500 requirements.txt\n\u2502 \u251c\u2500\u2500 package.json # Frontend\n\u2502 \u251c\u2500\u2500 package-lock.json # Frontend\n\u2502 \u2514\u2500\u2500 webpack.config.js # Frontend\n\u251c\u2500\u2500 dev/\n\u2502 \u251c\u2500\u2500 django.dockerfile\n\u2502 \u251c\u2500\u2500 webpack.dockerfile\n\u2502 \u2514\u2500\u2500 dev.env\n\u251c\u2500\u2500 .dockerignore\n\u251c\u2500\u2500 .gitignore\n\u251c\u2500\u2500 jsconfig.json\n\u251c\u2500\u2500 CONTRIBUTING.md\n\u251c\u2500\u2500 docker-compose.yml\n\u251c\u2500\u2500 LICENSE\n\u2514\u2500\u2500 README.md\n
Overall project structure
\u251c\u2500\u2500 frontend/\n\u2502 \u251c\u2500\u2500 src/\n\u2502 \u251c\u2500\u2500 assets/\n\u2502 \u251c\u2500\u2500 components/\n\u2502 \u251c\u2500\u2500 Apps.js\n\u2502 \u2514\u2500\u2500 <Components>/\n\u2502 \u251c\u2500\u2500 context/\n\u2502 \u251c\u2500\u2500 QualifiersContext.tsx\n\u2502 \u251c\u2500\u2500 pages/\n\u2502 \u251c\u2500\u2500 templates/\n\u2502 \u2514\u2500\u2500 index.html\n\u2502 \u251c\u2500\u2500 index.js\n\u2502 \u2514\u2500\u2500 index.scss\n\u2502 \u251c\u2500\u2500 static\n\u2502 \u2514\u2500\u2500 templates\n\u251c\u2500\u2500 tests/\n\u251c\u2500\u2500 .babelrc\n\u251c\u2500\u2500 .jest.config.js\n\u251c\u2500\u2500 package-lock.json\n\u251c\u2500\u2500 package.json\n\u2514\u2500\u2500 webpack.config.js\n
Frontend Architecture
These diagrams show how data flows through the app: Frontend and Backend UML diagrams
"},{"location":"developer/frontend/#summary","title":"Summary","text":"Frontend Tech Stack: React, Babel, webpack, Jest, React Testing Library, HTML, SCSS, JS, TailwindCSS
The over ninety percent of our frontend architecture is housed in our frontend/
directory. This directory is a Django app, which is a set of files that can be ported to any Django-based application.
Since our frontend is a Django app, it takes advantage of the way Django serves its static assets. Every Django app, by default, looks to the templates/
* directory within the app for the html
template file to serve. This template usually contains <script>
and <style>
tags denoting the location of SCSS and JS files. In Django, these files are usually located inside the static/
* directory. Likewise, our frontend app store our templates and static assets within these directories.
Despite these similiarties, however, the files in these two directories should never be manipulated by a developer. These files are automatically generated by an application called webpack via configurations in webpack.config.js
and .babelrc
.
The files that should be manipulated by developers are housed within the src/
directory. Inside of here are directories for assets/
, componenents/
, pages/
, router
, and templates/
. Each of these directories contains the files which webpack reads and then bundle into output files for the static/
and template/
directories.
templates/
and static/
directories contain within them a frontend/
directory in order to namespace template and static files. Although this serves little purpose for our project, it is a Django convention that prevents Django from confusing the templates/
and static/
directories from the frontend app vs another app.","text":""},{"location":"developer/frontend/#overview-of-directories-and-files","title":"Overview of Directories and Files","text":"static/
and templates/
directories.{ \"COPs\": { \"UI/UX\": [ \"UI/UX_Designer\", \"UX_Researcher\", \"UX_Writing\", \"UX_Practice_Lead\" ], \"Engineering\": [ \"Back_End_Developer\", \"Front_End_Developer\", \"Full_Stack_Developer\", \"Engineering_Practice_Lead\" ], \"Data_Science\": [ \"Data_Scientist\", \"Data_Analyst\", \"Data_Engineer\", \"Data_Science_Practice_Lead\" ], \"Project/Product_Management\": [ \"Product_Manager\", \"Project_Manager\", \"Business_Analyst\", \"Product_Owner\", \"Special_Projects_Coordinator\", \"Product_Management_Practice_Lead\" ], \"DevOps\": [ \"Site_Reliability_Engineer\", \"Data_Engineer\", \"Database_Architect\", \"Security_Engineer\", \"DevOps_Practice_Lead\" ] } }
static
directory.docker compose run webpack npm run test
.src/
directory.","text":""},{"location":"developer/frontend/#components-directory","title":"Components Directory","text":"\u251c\u2500\u2500 components/\n\u2502 \u251c\u2500\u2500 Basics/\n\u2502 \u251c\u2500\u2500 Colors.scss\n\u2502 \u2514\u2500\u2500 Titles.scss\n\u2502 \u251c\u2500\u2500 Buttons/\n\u2502 \u251c\u2500\u2500 Button.js\n\u2502 \u2514\u2500\u2500 Button.scss\n\u2502 \u251c\u2500\u2500 Cards/\n\u2502 \u251c\u2500\u2500 Cards.js\n\u2502 \u2514\u2500\u2500 Cards.scss\n\u2502 \u2514\u2500\u2500 <Components>/\n
A closer look at a theoretical expansion of the components directory
The components directory contains our site components. Each directory in here represents a different class of components, such as Buttons/
* or Cards/
*. Within these directories are the files necessary that creates these components. Likewise, the special Basics/
directory contains small CSS classes that are reused, but not, technically, components, such as text-size or text-colors.
...\n\nmodule.exports = {\n mode: 'development',\n entry: {\n index: \"./frontend/src/index.js\"\n },\n output: {\n clean: {\n keep: '.gitkeep'\n },\n filename: '[name].[contenthash].js',\n path: path.resolve(__dirname, 'frontend/static/frontend'),\n },\n devtool: 'inline-source-map',\n module: {\n rules: ...\n },\n optimization: {\n moduleIds: 'deterministic',\n runtimeChunk: 'single',\n splitChunks: ...\n },\n plugins: [\n new HtmlWebpackPlugin({\n filename: '../../templates/frontend/index.html',\n template: '/frontend/src/templates/index.html',\n }),\n ],\n watchOptions: {\n ignored: /node_modules/,\n },\n}\n
webpack.config.js (truncated)
Our webpack.config.js
file is one of the most important files to understanding how our frontend architecture comes together. Therefore, this section is dedicated to the settings that we have set for this file. Note that we do not explain all the settings, as some can be found and easily deduced from webpack's configuration and guides documentation.
index.js
imports all dependencies and files that makes up our product. Note that advanced multiple entry is possible, should we ever need it.static/
directory<script>
and <styles>
path by reading the template and outputing it with the path noted by filename. This output path follows Django's default template directory structure..gitkeep
file is there to give an empty file for git to preserve the otherwise empty directory when pushed onto GitHub. As you might have guessed, git does not push empty directories.","text":""},{"location":"developer/frontend/#why-do-we-separate-babel-from-webpack","title":"Why do we separate Babel from webpack?","text":"If you have explored documentation from webpack, you might learn that the babel-loader in module > rules can accept the settings noted in .babelrc
. The reason why we separate these settings into another file is because webpack is not, in theory, the only application that makes use of these settings. Although we have no other apps that makes use of .babelrc
at the moment, this can change in the future. Therefore, this separation of files is a form of future proofing.
Our tests exists inside the tests directory with subdirectories that follows frontend/src
. There is also __mock__/
which contains code that bypasses certain tricky imports, such as svg or SCSS assets, which are not needed when testing. In order to understand how to write tests, be sure to take a look at the documentation for React Testing Library, the parent DOM Testing Library, and the support libraries jest-dom and user-event.
To run these tests, use the command docker compose run webpack npm run test
(or with test:w
for watch mode). The tests are run through jest, while the other libraries support react testing by providing functions to render DOM elements and simulate user behavior.
Note: jest-environment-jsdom
is a library that is absolutely required to link jsdom to jest. It provides the classes necessary for jest to interpret the jsdom environment. This information is listed here as it is not listed in jest's or jsdom's docs.
In addition to testing the functioning of our components, we also test the accessability of it via the library, @axe-core/react. This library prints out accessibility issues onto the browser console, providing accessibiltiy testing once the HTML has fully rendered. That said, the library is known to give both false positives and false negatives. As always reading the official documentation is best when it comes to resolving these errors.
"},{"location":"developer/frontend/#additional-resources","title":"Additional Resources","text":"Sass Documentation React Documentation Webpack Documentation @babel/preset-react Documentation React Router Documentation Jest Documentation React Testing Library Documentation @axe-core/react Documentation WAI-ARIA Authoring Practices 1.1
"},{"location":"developer/github/","title":"GitHub Architecture","text":"\u251c\u2500\u2500 .github/ # Github\n\u2502 \u2514\u2500\u2500 ISSUE_TEMPLATE/\n\u251c\u2500\u2500 app/\n\u2502 \u251c\u2500\u2500 config/\n\u2502 \u2514\u2500\u2500 settings.py\n\u2502 \u251c\u2500\u2500 frontend/\n\u2502 \u251c\u2500\u2500 server/\n\u2502 \u251c\u2500\u2500 .babelrc\n\u2502 \u251c\u2500\u2500 manage.py\n\u2502 \u251c\u2500\u2500 requirements.txt\n\u2502 \u251c\u2500\u2500 package.json\n\u2502 \u251c\u2500\u2500 package-lock.json\n\u2502 \u2514\u2500\u2500 webpack.config.js\n\u251c\u2500\u2500 dev/\n\u2502 \u251c\u2500\u2500 django.dockerfile\n\u2502 \u251c\u2500\u2500 webpack.dockerfile\n\u2502 \u2514\u2500\u2500 dev.env\n\u251c\u2500\u2500 .dockerignore\n\u251c\u2500\u2500 .gitignore # Github\n\u251c\u2500\u2500 jsconfig.json\n\u251c\u2500\u2500 CONTRIBUTING.md # Github\n\u251c\u2500\u2500 docker-compose.yml\n\u251c\u2500\u2500 LICENSE # Github\n\u2514\u2500\u2500 README.md # Github\n
Overall project structure
\u251c\u2500\u2500 .github/\n\u2502 \u2514\u2500\u2500 ISSUE_TEMPLATE/\n\u251c\u2500\u2500 .gitignore\n\u251c\u2500\u2500 CONTRIBUTING.md\n\u251c\u2500\u2500 LICENSE\n\u2514\u2500\u2500 README.md/\n
GitHub structure
"},{"location":"developer/github/#summary","title":"Summary","text":""},{"location":"developer/github/#overview-of-directories-and-files","title":"Overview of Directories and Files","text":"This guide runs through the steps needed to create and run a local version of our project.
If you are ever stuck or need clarification, you can contact our team members or the development lead through our Slack or email, and schedule a pair programming session with one of our developers. All of us have been through these steps, and am more than happy to help. By helping you, we can better improve our documentation and grow this project!
"},{"location":"developer/installation/#required-downloads","title":"Required Downloads","text":"Git - Windows - macOS - Linux/Unix Docker - Windows - macOS - Linux/Unix Prettier - VSCode Extension
Note on macOS The macOS version of git involves downloading extra programs, such as Homebrew. In some cases this program can run up to 8GB of storage space, which might be too much for some. In that scenario, a miniature version of Homebrew can be installed through XCode. But do be warned that the containers for our project takes up a substantial amount of disk space as well. Do consider freeing up your disk space by deleting or backing up unneeded files, like photos or videos, and delete programs that are no longer useful. Your OS's native disk cleaner can also clear out unused cache files. "},{"location":"developer/installation/#environmental-setup","title":"Environmental Setup","text":"While developing, make sure to create new branches off of the develop
branch. To checkout the develop
branch into your local repository, you can do the following:
CivicTechJobs/
, in the terminal.git remote add upstream https://github.com/hackforla/CivicTechJobs.git
- this command adds the original hackforla CivicTechJobs github repo as a remote to your local repository and names it \"upstream\".git fetch upstream develop
- this command fetches the develop
branch.git checkout -b develop upstream/develop
- this command creates and checks out a new branch called \"develop\" that tracks the upstream develop
branch.CivicTechJobs/
, in the terminal.dev/
, create a file named, dev.env
.dev.env.example
. Afterwards, you must edit the lines specified below.cd frontend
and then npm install
. When this is finished, move back to the root directory cd ..
docker compose up --watch
to run the local server.http://localhost:8000
and you should see the front page of our website!The `--watch` flag enables hot module reloads during development. This flag requires a later version of Docker Compose(2.22.0).
If you are running into issues or getting errors running `docker compose up --watch`, please make sure you have installed the latest version of Docker and Docker Desktop on your machine.
"},{"location":"developer/installation/#frequently-asked-questions","title":"Frequently Asked Questions","text":"This section might answer some of the burning questions you have. If you cannot find it here, be sure to contact our team members or the development lead through our Slack or email.
"},{"location":"developer/installation/#troubleshooting-errors","title":"Troubleshooting Errors","text":""},{"location":"developer/installation/#1-the-command-docker-could-not-be-found","title":"1. The command 'docker' could not be found","text":"Make sure to turn on Docker by opening the Docker program on your desktop.
"},{"location":"developer/installation/#2-cant-find-a-suitable-configuration-file-in-this-directory-or-any-parent-not-found","title":"2. can't find a suitable configuration file in this directory or any parent: not found","text":"Make sure that your terminal location is in a directory with a docker-compose.yml
file. And make sure that the file is not hidden.
This can result for several reasons, such as havin your sockets overloaded. In order to prevent this, the best thing to do is to lower the amount of sockets used when performing npm install. Change this line in docker/webpack
:
RUN npm install
to:
RUN npm install --maxsockets=1
This should allow docker compose up
to work. Be sure to delete the addition once your image and container is set up.
This sometimes happen when npm did not install successfully. In this scenario, you need to manually install the dependencies inside the container. Generally the command to run a command inside a container is:
docker compose run [container name] [command to run in container]
In this scenario, the full command would be:
docker compose run webpack npm install
In this case, the index.html
file has incorrect ownership and/or permissions. To fix this, run the following command in the root directory of the CTJ repository:
sudo chown -R $USER:$USER
This will utilize superuser permissions to change the user and group ownership of all the files and directories in the current directory to the current user.
"},{"location":"developer/installation/#additional-resources","title":"Additional Resources","text":"Git Documentation Docker Documentation Frontend Architecture Backend Architecture DevOps Architecture GitHub Architecture
"},{"location":"developer/mkdocs-architecture/","title":"MKdocs Architecture","text":"\u251c\u2500\u2500 .github/\n\u2502 \u251c\u2500\u2500 ISSUE_TEMPLATE/\n\u2502 \u2514\u2500\u2500 workflows/\n\u2502 \u2514\u2500\u2500 mkdocs-build.yml # Docs\n\u251c\u2500\u2500 backend/\n\u251c\u2500\u2500 dev/\n\u251c\u2500\u2500 frontend/\n\u251c\u2500\u2500 mkdocs/ # Docs\n\u2502 \u251c\u2500\u2500 docs/\n\u2502 \u2514\u2500\u2500 mkdocs.yml # Docs\n\u251c\u2500\u2500 .dockerignore\n\u251c\u2500\u2500 .gitignore\n\u251c\u2500\u2500 CONTRIBUTING.md\n\u251c\u2500\u2500 docker-compose.yml\n\u251c\u2500\u2500 docker-compose.docs.yml # Docs\n\u251c\u2500\u2500 LICENSE\n\u2514\u2500\u2500 README.md\n
Overall project structure
\u251c\u2500\u2500 docs/\n\u2502 \u251c\u2500\u2500 assets/\n\u2502 \u251c\u2500\u2500 css/\n\u2502 \u251c\u2500\u2500 developer/\n\u2502 \u251c\u2500\u2500 joining-the-team/\n\u2502 \u251c\u2500\u2500 js/\n\u2502 \u2514\u2500\u2500 misc/\n\u251c\u2500\u2500 index.md\n\u251c\u2500\u2500 resources.md\n\u251c\u2500\u2500 mkdocs.yml\n
mkdocs directory structure
"},{"location":"developer/mkdocs-architecture/#summary","title":"Summary","text":"The MkDocs \"sub-project\" lives in the mkdocs/
folder. A development server can be run using the docker-compose.docs.yml
compose script. The mkdocs is set to automatically deploy to github pages using the mkdocs-build.yml
github action.
It is important to note that we are using Hack for LA's prebuilt docker mkdocs image for convenient setup. Please see the resources below for more information:
This prebuilt docker image makes it easy to get a mkdocs development server running with one command, without having to install python or mkdocs dependencies on your local machine. It also includes common useful plugins that we dont have to worry about installing ourselves, and already includes the mkdocs-material
theme pre-installed.
Our project implements the HFLA mkdocs image by pulling it inside the docker-compose.docs.yml
file:
name: civic-tech-jobs-mkdocs\n\nservices:\n mkdocs:\n container_name: mkdocs\n image: hackforlaops/mkdocs:latest\n command: mkdocs serve -a \"0.0.0.0:8005\"\n ports:\n - \"8005:8005\"\n volumes:\n - ./mkdocs:/app\n develop:\n watch:\n - action: sync\n path: ./mkdocs\n target: /app\n
Now when we run docker compose up like so:
docker-compose -f docker-compose.docs.yml up --watch\n
A mkdocs development server is started on http://localhost:8005
The url for the github pages site is: https://hackforla.github.io/CivicTechJobs/
(the website you are reading this on right now).
Our github repo is set to publish the docs to Github Pages using the gh-pages
branch. This setting can be configured in the project's Pages settings.
External Resources:
Relevant PR and Issue:
The docs are set to automatically deploy to github pages using the mkdocs-build.yml
github action. This action builds the mkdocs and saves the static files into the gh-pages
branch.
Links to the github action: Build MkDocs site (develop)
name: Build MkDocs site (develop)\n\non:\n push:\n branches:\n - develop\n paths:\n - \"mkdocs/**/**.md\"\n - \"mkdocs/mkdocs.yml\"\n workflow_dispatch:\n\npermissions:\n contents: write\n\njobs:\n deploy-docs:\n runs-on: ubuntu-latest\n if: github.actor != 'github-actions[bot]'\n steps:\n - uses: actions/checkout@v4\n - name: Configure Git Credentials\n run: |\n git config user.name github-actions[bot]\n git config user.email 41898282+github-actions[bot]@users.noreply.github.com\n - uses: actions/setup-python@v5\n with:\n python-version: 3.x\n - run: echo \"cache_id=$(date --utc '+%V')\" >> $GITHUB_ENV\n - uses: actions/cache@v4\n with:\n key: mkdocs-material-${{ env.cache_id }}\n path: .cache\n restore-keys: |\n mkdocs-material-\n - name: Install Dependencies\n run: pip install \\\n mkdocs-material==9.1.17 \\\n mkdocs-autolinks-plugin==0.7.1\n - name: Publish docs\n run: |\n cd mkdocs\n mkdocs gh-deploy --force\n
Workflow Overview
name: Build MkDocs site
- The name of this workflow is \"Build MkDocs site.\"on: push: - develop
- The workflow is triggered when there\u2019s a push to the develop branch. (We will change this to main
later)paths: ...
- The workflow will only run if the files being pushed are Markdown files (.md
) or the mkdocs.yml
configuration file inside the mkdocs directory.workflow_dispatch:
- This allows manual triggering of the workflow via the GitHub Actions interface.permissions: contents: write
- This grants the action permission to write contents to the repository. It's needed for deploying the site, which requires pushing to the gh-pages
branch.runs-on: ubuntu-latest
- This specifies that the job will run on the latest Ubuntu environment provided by GitHub Actions.if: github.actor != 'github-actions[bot]'
- This condition ensures that the job doesn\u2019t trigger if the GitHub Actions bot is the one making the changes. This prevents infinite loops where the action keeps triggering itself.uses: actions/checkout@v4
- This step checks out the repository code so the workflow can access the files.run: git config user.name github-actions[bot]
- Configures Git to use the github-actions[bot]
user for any commits or pushes that may happen during the deployment.git config user.email 41898282+github-actions[bot]@users.noreply.github.com
- Sets the email for the github-actions[bot] user.uses: actions/setup-python@v5
- This sets up a Python environment in the GitHub runner, which is necessary for installing and running MkDocs.Set environment variable for caching
run: echo \"cache_id=$(date --utc '+%V')\" >> $GITHUB_ENV
cache_id
to the current week of the year (%V
). This value will be used as the key for caching to ensure that the cache is updated weekly.Cache dependencies
uses: actions/cache@v4
- This step caches dependencies (to speed up future builds) in the .cache directory.with: key: mkdocs-material-${{ env.cache_id }}
- The cache key is based on the cache_id, so the cache is refreshed weekly.path: .cache
- Specifies that the cache should be stored in the .cache directory.restore-keys: mkdocs-material-
- This allows for fallback caching if an exact cache match is not found.Install Dependencies
run: pip install mkdocs-material==9.1.17 mkdocs-autolinks-plugin==0.7.1
mkdocs-material==9.1.17
: A popular theme for MkDocs.mkdocs-autolinks-plugin==0.7.1
: A plugin that automatically creates links between pages in your documentation based on their titles.Publish Documentation
run: cd mkdocs && mkdocs gh-deploy --force
mkdocs/
directory.mkdocs gh-deploy --force
. The --force
flag ensures that the contents of the GitHub Pages branch (gh-pages
) are overwritten with the latest deployment.This workflow automates the process of building and deploying a MkDocs site when changes are pushed to the develop branch. It does the following:
gh-deploy
.This workflow ensures the documentation is always up to date and available on GitHub Pages whenever changes are made to relevant Markdown files or the MkDocs configuration.
"},{"location":"developer/mkdocs-edit-instructions/","title":"How to Publish new Documentation","text":"The goal of this page is to document how to create and publish new changes to the CTJ documentation.
Writing documentation into mkdocs requires some knowledge of Markdown.
"},{"location":"developer/mkdocs-edit-instructions/#making-changes-to-the-mkdocs","title":"Making changes to the mkdocs","text":"What you essentially need to know:
.md
files located in the mkdocs/docs/
folder..md
file in the appropriate folder.mkdocs.yml
file.MkDocs provides a development server that makes it convenient to see your changes in localhost
before you deploy them to github.
For more a detailed editing guide please see the official MkDocs Tutorial
"},{"location":"developer/mkdocs-edit-instructions/#quickstart","title":"Quickstart","text":"To start the development server, simply go to the root of your project in the terminal and run the following command:
docker-compose -f docker-compose.docs.yml up --watch\n
Next, go to http://localhost:8005
in your browser.
Now when you save new changes to the .md
files, the respective page will automatically be updated in the browser.
When you are done editing, the next step is to deploy your changes.
"},{"location":"developer/mkdocs-edit-instructions/#deploying-your-changes","title":"Deploying your changes","text":"When you are satisfied with your edits, make a pull request so that they can be reviewed.
Once the pull request is approved and merged into develop
, the changes will be automatically deployed to the official CivicTechJobs documentation site (the site you are reading this page in right now). That's it!
If anything goes wrong, you can investigate the workflow in the project's github actions page
Note: At the moment, the docs are set to deploy from the develop
branch, using the github action located in mkdocs-build.yml
. This means that whenever a file is changed inside the mkdocs/
directory, and is merged into the develop
branch on github, the changes will be automatically deployed to the official site hosted on github pages. In the near future we will set it to deploy from the main
branch.
Check out our MkDocs Architecture page for more details on how it all fits together.
"},{"location":"developer/mkdocs-edit-instructions/#recap","title":"Recap","text":"To sum it all up, you can make changes in 4 easy steps:
docker-compose -f docker-compose.docs.yml up --watch
.md
files and observe them in http://localhost:8005
develop
branchWe are using mkdocs to handle documentation.
Developers should document their architectural and coding decisions, so that other team members can easily reference these docs whenever they are lost or confused or new to the project.
"},{"location":"developer/mkdocs-guide/#what-is-mkdocs","title":"What is MKdocs?","text":"MkDocs is a static site generator that is designed specifically for building project documentation. It allows you to write documentation using Markdown, a lightweight markup language that's easy to use, and generates a clean, professional website that can be hosted on our project's GitHub Pages.
Please see MkDocs - How to Edit for instructions on how to make changes to the CTJ documentation and publish new docs.
"},{"location":"developer/mkdocs-guide/#what-should-developers-document","title":"What should developers document?","text":"Code functionality
Setup Instructions
Common Use Cases
Troubleshooting
Code Examples
API Documentation
DRAFT NOT YET FILLED OUT
"},{"location":"joining-the-team/content-writer/#content-writer","title":"Content Writer","text":"Review existing copy on the CivicTechJobs.
Review the Figma for pages that are not yet published.
Review the Project Board and identify an actionable backlog item.
Communicate with PM your interest in being assigned a task.
DRAFT NOT YET FILLED OUT
"},{"location":"joining-the-team/data-scientist/#data-scientist","title":"Data Scientist","text":"Read the Readme.
Review the Project Board and identify an actionable backlog item. We are working to resolve some database architecture issues and are not onboarding new data scientist at this time.
Communicate with the PM on your interest in being assigned a task.
DRAFT NOT YET FILLED OUT
"},{"location":"joining-the-team/intro/#introduction","title":"Introduction","text":"Welcome to the Civic Tech Jobs team! This guide will help get you up to speed on what you need to know to get started as a project team member.
"},{"location":"joining-the-team/intro/#lets-go","title":"Let's go!","text":"If you have not read the Guide for New Volunteers, please do so.
Click the link that applies to you to find a sequence of immediate action steps:
Web Developer
UI/UX Designer
UI/UX Researcher
Data Scientist
Content Writer
Product Manager/Owner
Other Volunteer
"},{"location":"joining-the-team/intro/#accessibility-standards","title":"Accessibility standards","text":"Title III of the Americans with Disabilities Act (ADA) requires that all sites be accessible to people with disabilities. The World Wide Web (W3C) Consortium's Web Content Accessibility Guidelines (WCAG) 2.0 Level AA function as the current legal standard for site accessibility.
Get acquainted with accessibility: https://www.ada.gov/pcatoolkit/chap5toolkit.htm
"},{"location":"joining-the-team/other-volunteer/","title":"Other Volunteer","text":"DRAFT NOT YET FILLED OUT
"},{"location":"joining-the-team/other-volunteer/#other-volunteer","title":"Other Volunteer","text":"Get an overview of the project from the Wiki.
Review the Project Board.
Chat with a [INSERT PROJECT NAME HERE] PM to discuss your interest and background.
DRAFT NOT YET FILLED OUT
"},{"location":"joining-the-team/product-manager/#product-manager-and-owner","title":"Product Manager and Owner","text":"Each of the resources below can be considered a work-in-progress. These resources will evolve and adapt as the team and team needs change. Feel free to open an issue with a link to whichever resource needs improvement and a description of the suggested change.
Learn how we setup our GitHub Kanban boards and please comment if there is anything in the document that is unclear.
This Software Development Lifecycle Diagram is a sample of what the process is generally like at Hack for LA and each project is different.
Review our OKRS.
Communicate with other product team members and leadership to discuss project priorities and strategic direction.
Review the Project Board and the Product Management issues available on that board to identify an actionable backlog item.
Review Hack for LA Product Management Templates.
Review the UI/UX issues on the Project Management Board and identify an actionable backlog item.
Communicate with PM your interest in being assigned a task.
Ask your lead to invite you to the Civic Tech Jobs figma workspace
This is a generic software development lifecycle diagram for Hack for LA. We would like to talk to you about how this project is different.
Read about WCAG 2.0 accessibility standards.
DRAFT NOT YET FILLED OUT
"},{"location":"joining-the-team/web-developer/#web-developer","title":"Web Developer","text":""},{"location":"joining-the-team/web-developer/#starting-checklist","title":"Starting Checklist","text":"Read the development Readme and the CONTRIBUTING.md file set up your development environment.
Review the project board by the type of issue you are looking for. The Frontend Coding Project Board or the Backend Coding Project Board. Or you can check out the entire project board here.
Communicate with the PM about your interest in being assigned a task.
Your first commit will likely be an issue labeled good first issue. Check the board for those issues. Don't worry if you don't see anything now, we are working on it.
Read about WCAG 2.0 accessibility standards and set up third-party tools for compliance testing.
Review notes on security updates.
Site architecture document is coming soon.
DRAFT NOT YET FILLED OUT
"},{"location":"misc/ada-guide/#ada-guide","title":"ADA Guide","text":""},{"location":"misc/ada-guide/#which-accessibility-testing-tool-should-you-use","title":"Which accessibility testing tool should you use?","text":""},{"location":"misc/ada-guide/#overview","title":"Overview","text":"There are more than 100 accessibility testing tools. Figuring out which ones to use can be a black hole. For guidance we recommend this article: Which accessibility testing tool should you use?
"},{"location":"misc/ada-guide/#summary-of-article","title":"Summary of Article","text":"The author recommends using the tools in the following order fixing as you go along, since no one tool catches all the relevant issues
aXe SiteImprove Tenon WAVE Lighthouse
But if you want to test your site with other tools, here is a bigger list
"},{"location":"misc/glossary/","title":"Glossary","text":"DRAFT NOT YET FILLED OUT
"},{"location":"misc/glossary/#glossary","title":"Glossary","text":"When we have a shiny glossary it will come here.
Term Alternate terms Official Link Description"},{"location":"misc/history/","title":"History","text":"How Hack for LA evolved from in person onboarding to remote, and the iterative approach that we have taken to arrive at the need for a dedicated interface to list volunteer opportunities.
"},{"location":"misc/history/#pre-covid-times","title":"Pre-Covid times","text":"Hack for LA practiced in person recruiting on onboarding nights. It had its own benefits, like each volunteer felt valued and had agency
"},{"location":"misc/history/#2020-mid-2021","title":"2020-mid 2021","text":"The team later moved on to a new process where the open roles on each team were posted on the Hack For LA site. This led to:
Hack for LA moved to a new model where all new volunteer attend onboarding and then join a communities of practice (CoP) and no open roles are posted on the hackforla.org site. These CoPs have volunteer opportunity boards so that when project leads recruit, they can go to a larger group of people who are more likely to be a good fit for the role available. Also CoP leads can help provide coaching if someone is unsure of if they are a good fit. Listings at CoP allow the org to determine if the project is actually ready to receive volunteers.
The Hack for LA organization team has now green lighted a project to create a dedicated job board page where volunteers can search and find volunteer opportunities that match their goal and aspirations while still maintaining the involvement of onboarding and CoPs.
"},{"location":"misc/our-process/","title":"Our Process","text":"This page has links and details such as links to a spreadsheet with our research, etc. and what order we did things in. But less narrative and mostly links
"},{"location":"misc/research-wiki-template/","title":"Template for presenting research on wiki","text":"# [Name of Research]\n\n## Research Date:\n\n## Current Status\n\n## Overview Issue #:\n\n## Outstanding task items\n\n## Assets\n\n### Research Plan (including Audience Identification documentation)\n\n### Scripts\n\n### Interview recordings & Transcripts\n\n### Synthesis (Miro or Figjam)\n\n### Presentation of Findings\n\n### Action Items Spreadsheet\n
"},{"location":"misc/security-updates/","title":"Security Updates","text":"This project subscribes to GitHub's automated security alerting service. Occasionally the repository home page may have a yellow banner saying \"We have found a potential security vulnerability in one of your dependencies\" and a link to view the security alert. If you see this, please check our issues list to see if anyone has added an issue for fixing this. If not, please create an issue for this problem. If you feel up to it, please assign the issue to yourself and try to fix it. As with any issue, once you have fixed it on your fork of the repository, push the fixes to your fork and then open a pull request to merge this fix into the main repository.
GitHub's \"dependabot\" may try to generate an automated pull request to fix this issue. Please do not accept this pull request without verifying that it works by applying the update on your local copy of the site.
"},{"location":"misc/the-team/","title":"The Team","text":"Name Role Joyce Guo Product Manager Sabrina Heasley Product Manager Salima Yacoubi Soussane Product Manager Bitian Zhang Full Stack Developer Matt Pereira Full Stack Developer Will Gillis Full Stack Developer Sarah Sanger Software Developer Benny Van Software Developer Jen Chung UX/UI Designer Lead Tin Wei, Chung UX/UI Designer Lu Feng UX/UI Designer Gabriel Vicencio UX/UI Designer Melinda Sukosd UX Researcher Lead Leah Ellis UX Researcher Jenn Wu UX Researcher Nga Do UX Researcher"}]} \ No newline at end of file diff --git a/sitemap.xml b/sitemap.xml new file mode 100644 index 00000000..7e701e4b --- /dev/null +++ b/sitemap.xml @@ -0,0 +1,111 @@ + +