diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..d805dd6 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,36 @@ +# Description + +_Please include a summary of the change and which issue is fixed. Please also include relevant +motivation and context. List any dependencies that are required for this change._ + +Fixes # (issue) + +## Type of change + +_Please delete options that are not relevant._ + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as + expected) +- [ ] Documentation (update or new) + +## How Has This Been Tested? + +_Please describe the tests that you ran to verify your changes. Provide instructions so we can +reproduce. Please also list any relevant details for your test configuration_ + +## Testing Checklist + +- [ ] Tested in latest Chrome +- [ ] Tested in latest Safari +- [ ] Tested in latest Firefox + +## Checklist + +- [ ] My code follows the style guidelines of this project +- [ ] I have performed a self-review of my own code +- [ ] I have commented my code in hard-to-understand areas +- [ ] I have made corresponding changes to the documentation +- [ ] My changes generate no new warnings +- [ ] I have requested a review from ... on the Pull Request diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..4129545 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,29 @@ +name: CI + +on: + pull_request: + push: + branches: [main] + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 + - name: Linelint + uses: fernandrone/linelint@master + - name: Set up Node + uses: actions/setup-node@v1 + with: + node-version: 16.14.2 + - name: Install dependencies + run: npm install + - name: Prettier + run: npm run format:check + - name: Vale + run: | + sudo apt update + sudo apt install snapd + sudo snap install vale --edge + npm run prose:check diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..6240da8 --- /dev/null +++ b/.gitignore @@ -0,0 +1,21 @@ +# build output +dist/ +# generated types +.astro/ + +# dependencies +node_modules/ + +# logs +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* + + +# environment variables +.env +.env.production + +# macOS-specific files +.DS_Store diff --git a/.linelint.yml b/.linelint.yml new file mode 100644 index 0000000..8188b67 --- /dev/null +++ b/.linelint.yml @@ -0,0 +1,18 @@ +# 'true' will fix files +autofix: true + +# list of paths to ignore, uses gitignore syntaxes (executes before any rule) +ignore: + - .git/ + +rules: + # checks if file ends in a newline character + end-of-file: + # set to true to enable this rule + enable: true + + # set to true to disable autofix (if enabled globally) + disable-autofix: false + + # if true also checks if file ends in a single newline character + single-new-line: true diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..8dc0d6d --- /dev/null +++ b/.prettierignore @@ -0,0 +1,8 @@ +.vscode +node_modules +package.json +package-lock.json +yarn.lock +dist + + diff --git a/.prettierrc.js b/.prettierrc.js new file mode 100644 index 0000000..c8d19de --- /dev/null +++ b/.prettierrc.js @@ -0,0 +1,13 @@ +/** @type {import('prettier').Config} */ +module.exports = { + printWidth: 120, + semi: true, + singleQuote: true, + tabWidth: 2, + trailingComma: 'es5', + useTabs: false, + + plugins: ['prettier-plugin-astro'], + + overrides: [{ files: '*.astro', options: { parser: 'astro' } }], +}; diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 0000000..973fb85 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,12 @@ +# Vale configuration file. +# +# For more information, see https://errata-ai.gitbook.io/vale/getting-started/configuration. + +StylesPath = .vale +MinAlertLevel = suggestion + +[*.md] + + +# Ignore SVG markup +TokenIgnores = (\*\*\{\w*\}\*\*) \ No newline at end of file diff --git a/.vale/vale-json.tmpl b/.vale/vale-json.tmpl new file mode 100644 index 0000000..4240c5b --- /dev/null +++ b/.vale/vale-json.tmpl @@ -0,0 +1,58 @@ +{{- /* Modify Vale's output https://docs.errata.ai/vale/cli#--output */ -}} + +{{- /* Keep track of our various counts */ -}} + +{{- $e := 0 -}} +{{- $w := 0 -}} +{{- $s := 0 -}} +{{- $f := 0 -}} + +{{- /* Range over the linted files */ -}} + +{{- range .Files}} + +{{- $f = add1 $f -}} +{{- $path := .Path -}} + +{{- /* Range over the file's alerts */ -}} +[ + +{{- range $idx, $a := .Alerts -}} + +{{- $error := "" -}} +{{- if eq .Severity "error" -}} + {{- $error = .Severity -}} + {{- $e = add1 $e -}} +{{- else if eq .Severity "warning" -}} + {{- $error = .Severity -}} + {{- $w = add1 $w -}} +{{- else -}} + {{- $error = .Severity -}} + {{- $s = add1 $s -}} +{{- end}} + +{{- /* Variables setup */ -}} + +{{- $path = $path -}} +{{- $loc := printf "%d" .Line -}} +{{- $check := printf "%s" .Check -}} +{{- $message := printf "%s" .Message -}} +{{- $link := printf "%s" .Link -}} +{{- if $idx -}},{{- end -}} + +{{- /* Output */ -}} + + { + "description": "{{ $message }}", + "fingerprint": "{{ $path }}-{{ $loc }}", + "severity": "{{ $error }}", + "location": { + "path": "{{ $path }}", + "lines": { + "begin": {{ $loc }} + } + } + } +{{end -}} +{{end -}} +] \ No newline at end of file diff --git a/.vale/vale-tmpl b/.vale/vale-tmpl new file mode 100644 index 0000000..efd1c90 --- /dev/null +++ b/.vale/vale-tmpl @@ -0,0 +1,51 @@ +{{- /* Modify Vale's output https://docs.errata.ai/vale/cli#--output */ -}} + +{{- /* Keep track of our various counts */ -}} + +{{- $e := 0 -}} +{{- $w := 0 -}} +{{- $s := 0 -}} +{{- $f := 0 -}} + +{{- /* Range over the linted files */ -}} + +{{- range .Files}} + +{{- $f = add1 $f -}} +{{- $path := .Path | underline -}} + +{{- /* Range over the file's alerts */ -}} + +{{- range .Alerts -}} + +{{- $error := "" -}} +{{- if eq .Severity "error" -}} + {{- $error = .Severity | red -}} + {{- $e = add1 $e -}} +{{- else if eq .Severity "warning" -}} + {{- $error = .Severity | yellow -}} + {{- $w = add1 $w -}} +{{- else -}} + {{- $error = .Severity | blue -}} + {{- $s = add1 $s -}} +{{- end}} + +{{- /* Variables setup */ -}} + +{{- $path = $path -}} +{{- $loc := printf "Line %d, position %d" .Line (index .Span 0) -}} +{{- $check := printf "%s" .Check -}} +{{- $message := printf "%s" .Message -}} +{{- $link := printf "%s" .Link -}} + +{{- /* Output */ -}} + +{{ $path }}: + {{ $loc }} (rule {{ $check }}) + {{ $error }}: {{ $message }} + More information: {{ $link }} + +{{end -}} +{{end -}} + +{{- $e}} {{"errors" | red}}, {{$w}} {{"warnings" | yellow}}, and {{$s}} {{"suggestions" | blue}} found. \ No newline at end of file diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..22a1505 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,4 @@ +{ + "recommendations": ["astro-build.astro-vscode"], + "unwantedRecommendations": [] +} diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 0000000..0f11d25 --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,18 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "command": "./node_modules/.bin/astro dev", + "name": "Development server", + "request": "launch", + "type": "node-terminal" + }, + { + "name": "Docker Node.js Launch", + "type": "docker", + "request": "launch", + "preLaunchTask": "docker-run: debug", + "platform": "node" + } + ] +} diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 0000000..d416da5 --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,39 @@ +{ + "version": "2.0.0", + "tasks": [ + { + "type": "docker-build", + "label": "docker-build", + "platform": "node", + "dockerBuild": { + "dockerfile": "${workspaceFolder}/Dockerfile", + "context": "${workspaceFolder}", + "pull": true + } + }, + { + "type": "docker-run", + "label": "docker-run: release", + "dependsOn": [ + "docker-build" + ], + "platform": "node" + }, + { + "type": "docker-run", + "label": "docker-run: debug", + "dependsOn": [ + "docker-build" + ], + "dockerRun": { + "env": { + "DEBUG": "*", + "NODE_ENV": "development" + } + }, + "node": { + "enableDebugging": true + } + } + ] +} \ No newline at end of file diff --git a/README.md b/README.md index 9e6897b..f4227eb 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,164 @@ -# doubtfire-astro -Home for Ontrack technical documentation +# Contributing to Doubtfire Astro Repository + +This guide provides high-level details on how to contribute to the Doubtfire repositories. This repository reflects the code for Ontrack documentation website. + + +The Ontrack documentation website is a centralised repository for recording all technical documentation for Ontrack project. + +## Background + +The **doubtfire-astro** project provides the base repository containing information on technical document for OnTrack project. + +The OnTrack project contains following submodules: +- [doubtfire-api](https://github.com/thoth-tech/doubtfire-api) contain the backend RESTful API. This uses Rails' [active model](https://guides.rubyonrails.org/active_model_basics.html) with the [Grape REST api framework](https://github.com/ruby-grape/grape). +- [doubtfire-web](https://github.com/thoth-tech/doubtfire-web) hosts the frontend code implemented in [Angular](https://angular.io) and [AngularJS](https://angularjs.org). This implements the web application that connects to the backend api. +- [doubtfire-overseer](https://github.com/thoth-tech/doubtfire-overseer) provides facilities to run automated tasks on student submissions. Please get in touch with the core team if you want access to this repository. + + +### Working on onTrack documentation website + +To get started: + +1. Fork [doubtfire-astro](https://github.com/thoth-tech/doubtfire-astro) + + To push your contributions, you will need a fork of each repository. Contributions can then be made by making pull requests back into the main repositories. + +2. Clone your [doubtfire-astro](https://github.com/thoth-tech/doubtfire-astro). + + `git clone https://github.com/YOUR_USERNAME/doubtfire-astro` + +3. Open the cloned repository in VS code + - Open VS code + - Navigate to File and select ```Open folder``` + - Select the folder where you have cloned this repository + - you will be able to see all the files now + +4. To make changes/ add content to OnTrack Technical documentation website + - Go to the ```scr``` folder + - New Pages can be added or changes to existing pages can be made by navigating to ```content``` folder + - Images are required to be stored under ```assets``` folder + +5. Note - when adding new pages you would need to do following + - Make changes to ```content``` and also the ```astro.config.mjs``` file in parallel + e.g. We have a page for backend API list api_list.md the path of this needs to be mention in ```astro.config.mjs``` file + ``` + items: [ + { + label: 'Doubtfire API Documentation List', + link: '/backend/api/api_list', + }, + ] + ``` + +6. To see changes and verify changes being made are reflecting in Website follow the below steps: + - Open node terminal in your VS code project + - Run the command ```npm run dev``` + - This will load the website locally + - For any additional commands on Starlight refer to ```starlight.md``` + + + +## Pushing changes to Thoth Tech doubtfire-astro repository + +To start work on a new feature. + +1. Make your changes in locally +2. Create a **draft** [Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) and document the change you are working on. Doing this early will make sure that you get feedback on your work quickly. +4. Complete your work, pushing to your fork's feature branch. This will update your existing PR (no need to create new PRs) +5. Update the status of your PR removing the **draft** status, and flag someone in the Core team to review and incorporate your work. +6. Address any changes required. Pushing new commits to your branch to update the PR as needed. +7. Once your PR is merged you can delete your feature branch and repeat this process for new features... + + + +### Ensure you have your author credentials set up + +You should ensure your git user config details are set to the email address you use with GitHub: + +```bash +git config --global user.email "my-github-email@gmail.com" +git config --global user.name "Freddy Smith" +``` + +### Key Github commands + +**Step 1.** Make changes, and repeat until you are done: + +```bash +$ git add ... ; git commit ; git push # make changes, commit, and push to origin +``` + +**Step 2.** Submit a pull request and **if unable to merge**: + +```bash +$ git pull --ff upstream # merge upstream's branch in your feature branch +$ git add ... ; git commit # resolve merge conflicts and commit +$ git push origin # push your merge conflict resolution to origin +``` + + +## Commit Message Format + +We have precise rules over how our Git commit messages must be formatted. This format makes it easier to read the commit history. + +Each commit message consists of a header, a body, and a footer. + +```text +
+ + + +