Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New and shiny manual! #399

Merged
merged 1 commit into from
Oct 2, 2023
Merged

New and shiny manual! #399

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 80 additions & 4 deletions .github/workflows/main.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
on:
push:
branches: main
pull_request:
merge_group:

name: CI
jobs:

test-software:
runs-on: ubuntu-22.04
if: (github.event.ref == 'refs/heads/main' || github.event_name == 'pull_request') || github.repository != 'GlasgowEmbedded/glasgow'
runs-on: ubuntu-latest
strategy:
matrix:
python-version:
Expand Down Expand Up @@ -54,7 +54,8 @@ jobs:
run: pdm run test

build-firmware:
runs-on: ubuntu-22.04
if: (github.event.ref == 'refs/heads/main' || github.event_name == 'pull_request') || github.repository != 'GlasgowEmbedded/glasgow'
runs-on: ubuntu-latest
steps:
- name: Check out source code
uses: actions/checkout@v3
Expand All @@ -71,11 +72,86 @@ jobs:
working-directory: ./firmware
run: make

required: # group all `test (*)` workflows into one for the required status check
build-manual:
if: (github.event.ref == 'refs/heads/main' || github.event_name == 'pull_request') || github.repository != 'GlasgowEmbedded/glasgow'
runs-on: ubuntu-latest
defaults:
run:
working-directory: docs/manual
steps:
- name: Check out source code
uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Set up PDM
uses: pdm-project/setup-pdm@v3
- name: Install dependencies
run: |
pdm install
- name: Build documentation
run: |
pdm run build
- name: Upload documentation archive
uses: actions/upload-artifact@v3
with:
name: docs
path: docs/manual/out

required: # group all required workflows into one to avoid reconfiguring this in Actions settings
if: (github.event.ref == 'refs/heads/main' || github.event_name == 'pull_request') || github.repository != 'GlasgowEmbedded/glasgow'
needs:
- test-software
- build-firmware
- build-manual
runs-on: ubuntu-latest
steps:
- run: |
true
publish-manual:
needs: build-manual
if: (github.repository == 'GlasgowEmbedded/glasgow' && github.event.ref == 'refs/heads/main') || github.repository != 'GlasgowEmbedded/glasgow'
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- name: Check out source code
uses: actions/checkout@v3
- if: github.repository == 'GlasgowEmbedded/glasgow' && github.event.ref == 'refs/heads/main'
name: Inject documentation from artifact under latest/
uses: actions/download-artifact@v3
with:
name: docs
path: pages/latest/
- if: github.repository == 'GlasgowEmbedded/glasgow' && github.event.ref == 'refs/heads/main'
name: Add CNAME and redirect from the root to latest/
run: |
echo >pages/CNAME 'glasgow-embedded.org'
cat >pages/index.html <<END
<!DOCTYPE html>
<html lang="en-US">
<meta charset="utf-8">
<title>Redirecting&hellip;</title>
<link rel="canonical" href="latest/">
<script>location="latest/"</script>
<meta http-equiv="refresh" content="0; url=latest/">
<meta name="robots" content="noindex">
<h1>Redirecting&hellip;</h1>
<a href="latest/">Click here if you are not redirected.</a>
</html>
END
- if: github.repository != 'GlasgowEmbedded/glasgow'
name: Inject documentation from artifact under {branch}/
uses: actions/download-artifact@v3
with:
name: docs
path: pages/${{ github.ref_name }}/
- name: Disable Jekyll
run: |
touch pages/.nojekyll
- name: Publish documentation for a branch
uses: JamesIves/github-pages-deploy-action@releases/v4
with:
folder: pages/
clean: true
single-commit: true
47 changes: 1 addition & 46 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,46 +1 @@
# Contributing to Glasgow

## Contributing bug reports

Bug reports are always welcome! When reporting a bug, please include the following:

* The operating system;
* The version of Glasgow (use `glasgow --version`);
* The complete debug log (use `glasgow -vvv [command...]`).

## Contributing code

Glasgow does not strictly adhere to any specific Python or C coding standards. If your code is structured and formatted similarly to existing code, it is good enough.

### Vendor documentation

If you have used vendor documentation while writing the code you're contributing, it is necessary to:

* upload the documentation to the [Glasgow Archive][archive]; and
* reference the documentation at the top of the file in the following format:

```
Ref: <insert vendor documentation title or, if absent, URL here>
Document Number: <insert vendor document number here, or omit the field if absent>
Accession: <insert Glasgow Archive accession number here>
```
If you cannot upload the documentation to the archive because it is under NDA and/or watermarked, contact the maintainers for assistance. Often, it is possible to achieve sufficient coverage using techniques such as using existing leaked documents or parallel construction.
[archive]: https://github.com/GlasgowEmbedded/Glasgow-Archive
### Writing commit messages
When modifying Python code, the first line of a commit message should, if possible, start with the name of the module that is being modified, such that `git log --grep` can be easily used for filtering. E.g.:
protocol.jtag_svf: accept and ignore whitespace in scan data.
When modifying firmware, the first line of a commit message should start with `firmware`. E.g.:
firmware: fix an operator precedence issue.
When modifying schematics or layout, the first line of a commit message should start with the revision. E.g.:
revC: swap U2/U3, fix DRC issue.
If none of the cases above are a good fit, any descriptive message is sufficient.
For information on contribution, please refer to the [official documentation](https://glasgow-embedded.org/latest/contribute.html).
2 changes: 1 addition & 1 deletion LICENSE-0BSD.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Copyright (C) 2018 [email protected]
Copyright (C) Glasgow Interface Explorer contributors

Permission to use, copy, modify, and/or distribute this software for
any purpose with or without fee is hereby granted.
Expand Down
Loading