This repo contains configuration that builds the service-resources portal. The portal stores the data for the up to date Arcimoto technical documentation, provided by the Technical Writing department, published by this tool for access by onsite vehicle technicians, via a secured web portal.
This repo uses an AWS CloudFormation template to build a interconnected set of lambdas, Cognito user pool, IAM and roles and policies. It uses an S3 bucket configured to serve it's data as a website via a secured CloudFront deployment for the onsite vehicle technicians to access the up to date technical documentation.
- The CloudFormation template sets up the AWS infrastructure.
- The HTML structure in the
resourcesfolder sits in the s3 bucket, with the lambdas authenticating users against the cognito user pool for access control. - The content in the
resources/docsfolder is a historical history of the documentation section of the service portal. The Technical Writing department exports that content and commits it as part of the process to push a new version live. - The content in the
resources/firmwarefolder is an initial push of the firmware modules, but is not updated as part of the current deploy process and should be treated as outdated and not used.
https://service-resources.arcimoto.com (Production instance)
https://dev.service-resources.arcimoto.com (Dev Instance)
Cord Slatton
We use the Angular git commit style
Full (long) version:
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
Short version
<type>(<scope>): <subject>
See https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format more details
VS Code extension that helps you to make the commit msg, no need to remember your scope, etc.: https://marketplace.visualstudio.com/items?itemName=Jhecht.git-angular
We use the allowed types from https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format
We use custom scopes per repository, see scopes below.
- config
- root
The docs folder is built by The Technical Writing department from a MadCap Flare output using the HTML5SideNav MadCap Flare template style. That content is uploaded manually using s3Browser, configured on the Technical Operations user's (typically Larry Carey) local computer.
The firmware folder is updated automatically via a bitbucket CI pipeline from the deployedFirmware repo master branch.
The content in the Service Resources Portal comes from the /resources/docs/HTML5SideNav folder in this repository. When a merge is made to the dev or master branch the Documentation section of dev.service-resources.arcimoto.com or service-resources.arcimoto.com is updated.
- Create a new feature branch from the
devbranch that is named according to a reasonable stable naming schema. Our common naming schema includes the ticket prefix to link it in Jira and then a short relevant description. Branch names do not allow spaces. Example of Arcimoto common schema:TEL-123-example-functionality-change. If this schema does not work for you, create one that does and stick to it. - Commit the changes to the feature branch for the revision being published.
- Push the feature branch to BitBucket
- Create a Pull Request (PR) from the feature branch to
dev - Satisfy the merge conditions on the PR to allow it to merge: approval of reviewers, etc.
- Merge to
dev - Allow repository pipeline to run for
dev- this deploys the content to the Services Resources Portal Dev, and notifies the concerned parties of the update - Review content on Services Resources Portal Dev
- If content needs revision before release to production then make those revisions to the files and go back to step 2
- If the content passes review at the Service Resources Poral Dev then make a PR in BitBucket from
devtomaster - Satisfy the merge conditions on the PR to allow it to merge: approval of reviewers, etc.
- Merge to
master - Allow repository pipeline to run for
master- this deploys the content to the Services Resources Portal, and notifies the concerned parties of the update - Review content on Services Resources Portal to make sure it matches the release
You need to be able to perform basic git actions of clone a repo, change branches, commit, push and pull. You have to install git itself first. VSCode can help you perform git actions easily with a GUI. If you have a preferred way of interacting with git you are comfortable with, feel free to use that.
- Download and Install git on Windows using all the default options
- Download, Install and Open VSCode
- Set Git Bash as your default terminal in VSCode:
Ctrl + Shift + Pto open the VSCode command palette- Type "Select Default Profile" and select it from the palette
- Select
Git Bashfrom the list of terminal options
- Open a command line terminal window within VSCode (View Menu -> Terminal or Ctrl + Alt + `)
- Setup an ssh key for use with BitBucket
- Select the
Source Controltab along the far left-hand icon based sidebar of VSCode (the git branch icon: it looks like three circles connnected by lines, hovering over the icon will tell you the name of the panel) - Select the
Clone Repositorybutton - Enter the Repository URL
[email protected]:arcimotocode1/service-resources-portal.gitin the field that drops down and hit enter. - This opens a file navigation window to select the location on your computer the repository files will download: navigate to an appropriate location and confirm.
- Once the download is complete select the
Open Folderbutton in the left-hand panel of VSCode and navigate to the location you selected in the previous step and confirm - Along the bottom panel of VSCode to the far left is the git branch icon (3 circles connected by lines) with the name of the branch you are on, it should start on the
masterbranch. Click the wordmaster, the VSCode command palette will open at the top of the window. Selectorigin/devto check out a local copy of thedevbranch. You need thedevbranch locally: each feature branch for releasing an update branches fromdev. See theHow to Release (Git Flow)section above for more information.
The MadCap Flare output HTML5SideNav folder can be output anywhere on your computer but will need to end up within this repo on your computer at resources/docs to work correctly. The easiest way to set this up will be to output directly to resources/docs within this repo, so it replaces the old content with the new, at which point you can commit the changes. See the How to Release (Git Flow) section above for more information.
The login to the production and dev portals are each controlled by a Cognito user pool. IT manages the allowed users based on the list of employed technicians. Each user in a given pool (production or dev) has equal permissions - pure authentication.
The IT and Vehicle Maintenance departments maintain their own documentation about their processes for this system.