the calendar is your timesheet
_{Keep your calendar up-to-date with what you work on, and that's it. You're done.}

📖 Table of Contents

➤ Table of Contents

• ➤ Roadmap
• ➤ Backlog
• ➤ Environments
• ➤ Contributing
  • Getting started
    • Set up environment
  • Code structure
  • Node version
  • Authentication
    • Google
  • Branching / Deploying
    • Main branch
    • Dev branch
  • Feature branches
    • Naming conventions
    • See also
  • GraphQL
    • Extensions for VS Code
  • Documentation
• ➤ Contributors

➤ Roadmap

Milestone	Release date	Version
💧  1 -  Hydrogen	03.02.2020
🎈  2 -  Helium	02.04.2020
🔋  3 -  Lithium	11.05.2020
🛰  4 -  Beryllium	22.05.2020
☄️  5 -  Boron	19.08.2020
🌱  6 -  Carbon	09.09.2020
💨  7 -  Nitrogen	15.10.2020
🅾️  8 -  Oxygen	15.12.2020
🦷  9 -  Fluor	27.04.2021
💡  10 -  Neon	16.11.2022
🧂  11 -  Sodium	17.04.2023
🧲  12 -  Magnesium	21.02 2024
⚪  13 -  Aluminium	Q1/Q2 2024
🛎️  14 -  Silisium	Q1/Q2 2025

➤ Backlog

Our backlog can be found here.

➤ Environments

Environment	Branch/Tag	CI	Status
Production	main	Yes
Development (new features)	dev and feat/	Yes
Staging (pre-prod)	Release tags	Yes

➤ Contributing

Contributions are very velcome! Here's some guidance to get started! ❤️

Getting started

1. Check out the dev branch
2. Run npm install
3. Run npm run-script create-env to create your own .env file for local testing
4. Set neccessary parameters in your new .env file (see Set up .env below)
5. Install the Azure App Service extension for vscode
6. Install the ESLint extension for vscode
7. Install the i18n Ally extension for vscode
8. Create an Azure app registration, or ask one of the maintainers for access to an existing one
9. Run npm run-script watch to watch both server and client changes concurrently

The following permissions are required by Azure App Registration:

Set up environment

You've copied .env.sample into .env, anually or using npm run-script create-env.

Now you need to set the required environment variables from this table:

Key	Description	Required
AUTH_PROVIDERS	Auth providers. E.g. azuread-openidconnect and google.	Yes
MICROSOFT_CLIENT_ID	ID of the AD application registration.	Yes
MICROSOFT_CLIENT_SECRET	Password/secret of the AD application registration.	Yes
MICROSOFT_REDIRECT_URI	Redirect URL for Microsoft (azuread-openidconnect) login	Yes
MICROSOFT_SCOPES	Scopes for Microsoft Graph queries. See https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent.	Yes
GOOGLE_CLIENT_ID	ID of the Google application registration	No
GOOGLE_CLIENT_SECRET	Password/secret of the Google registration.	No
GOOGLE_REDIRECT_URI	Redirect URL for Google login	No
GOOGLE_SCOPES	Scopes for Google APIs and login	No
PORT	Defaults to 9001	No
SESSION_NAME	A unique name for the sessions.	No
SESSION_SIGNING_KEY	Just a random string to secure the sessions.	Yes
REDIS_CACHE_HOSTNAME	Hostname for the Redis cache	Yes
REDIS_CACHE_KEY	Secret key for the Redis cache	Yes
APOLLO_KEY	Key for reporting to Apollo Studio	Yes
APOLLO_GRAPH_VARIANT	Graph variant for reporting to Apollo Studio. See this article	Yes
MONGO_DB_CONNECTION_STRING	Connection string for MongoDB	Yes
MONGO_DB_DB_NAME	Database name for MongoDB	Yes
API_TOKEN_SECRET	Secret to generate API tokens	Yes
DEBUG	To debug the Node backend. E.g. app* to see all logs from app. See debug.	No
LAUNCH_BROWSER	Set to 1 if you want to automatically open did in the browser when running watch task.	No

Code structure

Folder/File	Description
/shared	Shared code between client and server
/shared/config/security	Shared security configuration used by both the client and the server
/shared/utils/date	Shared date utilities used by both the client and the server
/client	Client TypeScript source using e.g. React and Apollo Client`.
/client/app	React app entry point
/client/app	React app parts
/client/common	Common elements like icons etc
/client/components	React components reusable throughout the solution
/client/graphql	Graphql implementation for the client using @apollo/client
/client/helpers	Helper functions
/client/pages	Main pages of the solution
/client/types	Types, models and interfaces
/client/utils	Utility functions
/client/index.tsx	Main entry point for the app
/server/public	Public assets, static files hosted under "/"
/server/routes	expressjs routes using hbs views
/server/graphql	GraphQL implementation
/server/graphql/resolvers	GraphQL resolvers, queries and mutations
/server/middleware	Server side Express middleware functions
/server/middleware/passport	passport authentication middleware
/server/services	Services (MS Graph and Azure Table Storage)
/server/utils	Utilities
/server/views	Express HBS views
/server/app.ts	Express app
/server/index.ts	Node.js server

Node version

NB: did should be developed with node 18.12.0

It's recommended to use nvm. We have a .nvrc with node version set to 18.12.0.

Authentication

did supports authentication with both Microsoft (azuread-openidconnect) and Google, but google support is in experimental state only supporting adding gmail accounts as externals to an existing Microsoft did subscription.

The auth providers are set in process.env.AUTH_PROVIDERS and sent to the client through GraphQL query authProviders.

Google

See wiki for more details on using did with Google.

Branching / Deploying

Main branch

The /main branch requires pull requests, and is set up with a CI/CD pipeline which deploys to did.puzzlepart.com

Dev branch

The /dev branch also requires pull requests, and is set up with a CI/CD pipeline which deploys to didapp-dev.azurewebsites.net.

Feature branches

For new features use the naming convention below. A CI/CD pipeline which deploys to didapp-dev.azurewebsites.net is set up for branches matching the pattern feat/* and dev.

Naming conventions

You are encouraged to branch with either of the following prefixes

• hotfix/
• bugfix/
• feat/

See also

See also A successful Git branching model

If you want to test with your web app, checkout Creating your own app registration in the Azure Portal in our wiki.

GraphQL

Extensions for VS Code

The extension Apollo extension for VS Code is recommended for working with GraphQL in vscode.

The Apollo VS Code extension provides an all-in-one tooling experience for developing apps with Apollo.

The extension enables you to:

• Add syntax highlighting for GraphQL files and gql templates inside JavaScript files
• Get instant feedback and intelligent autocomplete for fields, arguments, types, and variables as you write queries
• Manage client side schema alongside remote schema
• See performance information inline with your query definitions
• Validate field and argument usage in operations
• Navigate projects more easily with jump-to and peek-at definitions
• Manage client-only schemas
• Switch graph variants to work with schemas running on different environments

Documentation

The client is documented here and the server is documented here.

We use https://studio.apollographql.com/ for GraphQL schema documentation.

➤ Contributors

Carl Joakim Damsleth	Ole Martin Pettersen	Ole Kristian Mørch-Storstein
[email protected]	[email protected]	[email protected]