mirror of
https://github.com/web3privacy/docs
synced 2024-10-15 18:46:26 +02:00
Merge pull request #32 from niclaz/contributor-guides
This commit is contained in:
PG
GitHub
commit
74df03b241
6 changed files with 269 additions and 35 deletions
|
|
@ -78,7 +78,11 @@ export default defineConfig({
|
|||
{ label: 'Contributors guide', link: '/contributors/index' },
|
||||
{ label: 'Workgroups', link: '/contributors/workgroups' },
|
||||
{ label: 'Git repositories', link: '/contributors/git' },
|
||||
{ label: 'Guide: how to deploy event website', link: '/contributors/deploy-event-website' },
|
||||
{ label: 'Guide: how to add entry to docs', link: '/contributors/add-entry-to-docs' },
|
||||
{ label: 'Guide: how to add event to website', link: '/contributors/add-event-to-website' },
|
||||
{ label: 'Guide: how to add speaker to data', link: '/contributors/add-speaker-to-data' },
|
||||
{ label: 'Guide: how to use gen-img front-end', link: '/contributors/gen-img-front-end' },
|
||||
{ label: 'Guide: how to deploy a W3PN events website', link: '/contributors/deploy-event-website' },
|
||||
{ label: 'Code of conduct', link: '/get-involved/code-of-conduct' },
|
||||
]
|
||||
},
|
||||
|
|
|
|||
52
src/content/docs/contributors/add-entry-to-docs.md
Normal file
52
src/content/docs/contributors/add-entry-to-docs.md
Normal file
|
|
@ -0,0 +1,52 @@
|
|||
---
|
||||
title: How to add an entry to the Docs
|
||||
---
|
||||
|
||||
`WORK IN PROGRESS`
|
||||
|
||||
## Preamble
|
||||
|
||||
|
||||
#### Quick-reference:
|
||||
[https://github.com/web3privacy/REPOSITORY](https://github.com/web3privacy/REPOSITORY)
|
||||
|
||||
## Pre-requisites
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
|
||||
## Step-by-step Guide
|
||||
|
||||
### Part 1: Setup
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
### Part 2: Commits
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
### Part 3: Testing
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
### Tips & Tooling
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
### Troubleshooting
|
||||
- Ask in W3PN chats for support or help
|
||||
-
|
||||
-
|
||||
|
||||
### External resources
|
||||
|
||||
[Github Pages Documentation](https://docs.github.com/en/pages)
|
||||
|
|
@ -6,7 +6,7 @@ title: How to add an event to the web3privacy now website
|
|||
|
||||
The main project website is [web3privacy.info](https://web3privacy.info) and is auto-deployed via Github Pages leveraging the [Astro framework](https://astro.build/) but the data for the events listed, speaker profiles, W3P members/community partners, research and project is aggregated from our data repository and not the Astro code that runs the main website.
|
||||
|
||||
Therefore to add an event you need to edit the code in the Data repository of Web3privacy now, so that it auto-deploys a json output that is visible at [data.web3privacy.info](https://data.web3privacy.info) from which the Events are indexed, where data and images for speakers and the event are scrapped and presented on the main project website.
|
||||
Therefore to add an event you need to edit the code in the Data repository of Web3privacy now, so that it auto-deploys a json output that is visible at [data.web3privacy.info](https://data.web3privacy.info) from which the Events are indexed, where data and images for speakers and the event are scrapped and presented on the main project website. Please take note that within the Data repository all 'speakers' are 'persons' and can be found within the 'people' folder of the code.
|
||||
|
||||
**Please advise:** It is essential to distinguish these two repositories and ensure you are not making edits to /web when you are adding a new event:
|
||||
- /web code repository: [https://github.com/web3privacy/web](https://github.com/web3privacy/web)
|
||||
|
|
@ -34,7 +34,7 @@ Attention: to add a new event to the Web3privacy website **you do NOT need to ma
|
|||
[naming convention for event 'id'](https://docs.web3privacy.info/events/#naming-conventions)
|
||||
|
||||
## Pre-requisites
|
||||
- Have a Github account to create a PR in this repository[https://github.com/web3privacy/data](https://github.com/web3privacy/data)
|
||||
- Have a Github account to create a fork of this repository[https://github.com/web3privacy/data](https://github.com/web3privacy/data)
|
||||
- Have the relevant event information on hand (time, date, city, speakers, etc)
|
||||
- Have generated images for the event using the gen-img front-end (see Part 3 below)
|
||||
- Knowledge of our naming convention for event 'id' (how we name events) as [described here](https://docs.web3privacy.info/events/#naming-conventions) - for example: the 2024 congress in Bangkok has an id of `c24bkk`
|
||||
|
|
@ -78,7 +78,7 @@ Attention: to add a new event to the Web3privacy website **you do NOT need to ma
|
|||
|
||||
### Part 1: Setup
|
||||
- [ ] Sign in to Github and go to the [Data repository](https://github.com/web3privacy/data)
|
||||
- [ ] Make a fork of the Data repository, and proceed to make the edits in your fork
|
||||
- [ ] Make a fork of the Data repository, and proceed to make the edits within your fork of the code
|
||||
- [ ] Collect the following information for the new event: date, location, lead person(s), registration link, some of the confirmed speakers
|
||||
|
||||
|
||||
|
|
@ -90,7 +90,7 @@ Attention: to add a new event to the Web3privacy website **you do NOT need to ma
|
|||
- id:
|
||||
- date:
|
||||
```
|
||||
- [ ] the following are optional data points, which you should add to make the website listing look better
|
||||
- [ ] the following are optional data fields, which you should add to make the website listing look better
|
||||
```
|
||||
- issue:
|
||||
- type:
|
||||
|
|
@ -112,7 +112,7 @@ Attention: to add a new event to the Web3privacy website **you do NOT need to ma
|
|||
- design
|
||||
```
|
||||
|
||||
- [ ] For the full schema and what each of these data points are requesting see [data/schema/index.yaml between lines 27 - 103](https://github.com/web3privacy/data/blob/main/schema/index.yaml)
|
||||
- [ ] For the full schema and what each of these data fields are requesting see [data/schema/index.yaml between lines 27 - 103](https://github.com/web3privacy/data/blob/main/schema/index.yaml)
|
||||
- [ ] A good practice would be to find an event of the same `type`, copying it's entry in the index.yaml and then replacing the relevant information. For example to list the next Web3Privacy Congress, go to last year's edition and copy that as a template for your entry.
|
||||
- [ ] Once you added the event to the index.yaml, navigate to the relevant folder (sub-divided by year) within the _images folder of /events: [https://github.com/web3privacy/data/tree/main/src/events/_images](https://github.com/web3privacy/data/tree/main/src/events/_images)
|
||||
- [ ] Here is where you will be uploading 5 images for the event you added using the gen-img script explained below in Part 3.
|
||||
|
|
@ -128,16 +128,16 @@ https://github.com/web3privacy/web/tree/main/public/gen-img/events
|
|||
- [ ] Double check the content and images are there, then you can create a Pull Request from your fork into the main /data repository.
|
||||
|
||||
### Part 4: Refreshing data and synching
|
||||
- [ ] Once the PR is merged, verify there are no issues within the Github Pages deployment. To do this visit the Actions page and see if any recent Actions have failed (red circle indicates this).
|
||||
- [ ] Once the Pull Request is merged, verify there are no issues within the Github Pages deployment. To do this visit the Actions page and see if any recent Actions have failed (red circle indicates this).
|
||||
- [ ] Request that the /data maintainer runs the [W3PN data refresh Action](https://github.com/web3privacy/data/actions/workflows/data-refresh.yml)
|
||||
- [ ] Request that the /data maintainer runs the [sync Action](https://github.com/web3privacy/data/actions/workflows/sync.yml)
|
||||
- [ ] Check the event listed in visible on data.web3privacy.info and that images and thumbs have been properly generated by scripts
|
||||
- [ ] Wait 6 hours for the automated scripts within the /web code base to activate and scrape the appropriate data from data.web3privacy.info
|
||||
- [ ] navigate to the events section of the website and verify all is correct: [https://web3privacy.info/events](https://web3privacy.info/events)
|
||||
|
||||
### Tooling
|
||||
https://web3privacy.info/gen/event/
|
||||
https://github.com/web3privacy/web/tree/main/public/gen-img/events
|
||||
### Tips & Tooling
|
||||
- [ ] [https://web3privacy.info/gen/event](https://web3privacy.info/gen/event)
|
||||
- [ ] [https://github.com/web3privacy/web/tree/main/public/gen-img/events](https://github.com/web3privacy/web/tree/main/public/gen-img/events)
|
||||
|
||||
### Troubleshooting
|
||||
- Ask in W3PN chats for support or help
|
||||
|
|
@ -149,4 +149,4 @@ https://github.com/web3privacy/web/tree/main/public/gen-img/events
|
|||
|
||||
[Astro documentation](https://docs.astro.build/en/getting-started/)
|
||||
|
||||
[Example PR of adding an event to Data repository](https://github.com/web3privacy/data/pull/5)
|
||||
[Example Pull Request adding an event to Data repository](https://github.com/web3privacy/data/pull/5)
|
||||
|
|
|
|||
|
|
@ -1,46 +1,109 @@
|
|||
---
|
||||
title: How to add speakers to data.web3privacy.info json
|
||||
title: How to add an event to the web3privacy now website
|
||||
---
|
||||
|
||||
`WORK IN PROGRESS`
|
||||
|
||||
## Preamble
|
||||
|
||||
The main project website is [web3privacy.info](https://web3privacy.info) and is auto-deployed via Github Pages leveraging the [Astro framework](https://astro.build/) but the data for the events listed, speaker profiles, W3P members/community partners, research and project is aggregated from our data repository and not the Astro code that runs the main website.
|
||||
|
||||
Therefore to add a speaker to any of our websites you need to edit the code in the Data repository of Web3privacy Now, so that it auto-deploys a json output that is visible at [data.web3privacy.info](https://data.web3privacy.info), from where data and images for speakers are scrapped and presented elsewhere.
|
||||
|
||||
For example the main project website uses a web framework called Astro, which scrapes data.web3privacy.info and presents it with all the pretty HTML/CSS/JS elements needed for modern websites. This means that if you update a person's `caption` field because they changed thier job title this edit will be displayed the same way throughout the whole website where that person is a speaker or otherwise listed. This is the power of Astro but as a result it requires a different approach to editing website contents, the majority of content is contained within the Data repository of Web3Privacy Now
|
||||
|
||||
#### Quick-reference:
|
||||
[https://github.com/web3privacy/data](https://github.com/web3privacy/data)
|
||||
|
||||
|
||||
## Pre-requisites
|
||||
-
|
||||
-
|
||||
- Have a Github account to create a fork of this repository: [https://github.com/web3privacy/data](https://github.com/web3privacy/data)
|
||||
- Have the person's information on hand (name, caption information, social media handles)
|
||||
- Have a picture or image for the person to upload to the database (.png or .img format)
|
||||
|
||||
|
||||
## Step-by-step Guide
|
||||
|
||||
### Example code for the guide
|
||||
|
||||
### Part 1: Github
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
```
|
||||
name: Satoshi Nakamoto
|
||||
caption: Cypherpunk, Visionary and Creator of [Bitcoin](https://bitcoin.org)
|
||||
refs:
|
||||
email: satoshin@gmx.com
|
||||
```
|
||||
|
||||
### Part 2:
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
### Part 1: Setup
|
||||
- [ ] Sign in to Github and go to the [Data repository](https://github.com/web3privacy/data)
|
||||
- [ ] Make a fork of the Data repository, and proceed to make the edits within your fork of the code
|
||||
- [ ] Gather the data for the new person(s) that you are adding to the database (the only required field is `name` - this can be a pseudonym)
|
||||
- [ ] For each new person you are adding have one image for them, in either .png or .jpg format, which follows specific naming convention (explanation of this is further down)
|
||||
|
||||
### Part 2: Data repository
|
||||
- [ ] Navigate to the `people` folder within the /data/src/ directory: [https://github.com/web3privacy/data/tree/main/src/people](https://github.com/web3privacy/data/tree/main/src/people)
|
||||
- [ ] All the people/persons within the Web3Privacy ecosystem (speakers, core-contributors, team, etc) are stored here
|
||||
- [ ] Each person has a yaml file with their data listed therein and an image in the /_images folder with the same name
|
||||
- [ ] There is only one required data field for a valid person yaml:
|
||||
```
|
||||
- name:
|
||||
```
|
||||
|
||||
- [ ] the following are optional data fields, which you should try to fill in to make the person profile look nice online
|
||||
```
|
||||
- nickname:
|
||||
- caption: (can include markdown URL links)
|
||||
- country: (two letter lower-case country code)
|
||||
- refs: (twitter, linkedin, bsky, github, matrix, email - just the usernames)
|
||||
- imageUrl: (only to be used if the image is not within the _images folder)
|
||||
```
|
||||
|
||||
- [ ] For the full schema and what each of these data fields are requesting see [data/schema/index.yaml between lines 104 - 142](https://github.com/web3privacy/data/blob/main/schema/index.yaml)
|
||||
- [ ] Please note that some data fields such as `id` and `thumbs` are not meant to listed in the person yaml file.
|
||||
- [ ] For the `refs` data field it is very important to list only the handles and that each 'sub-category' is indented by two spaces after the `refs` field
|
||||
- [ ] To see a full example of what this looks like scroll to the bottom of this guide.
|
||||
|
||||
### Part 3: Upload the person image
|
||||
- [ ] Once you added the new yaml file, navigate to the _images folder within /people: [https://github.com/web3privacy/data/tree/main/src/people/_images](https://github.com/web3privacy/data/tree/main/src/people/_images)
|
||||
- [ ] Here is where you will be uploading an image for the person using the same name for the image as the yaml file. This is important for the database to assign the right image to the right person, please check the file name is correct prior to uploading your files to your forked code. **Using the example code** satoshi-nakamoto.yaml will have an associated image file named satoshi-nakamoto.png
|
||||
- [ ] If you want to person image to reference some external source, you can use the `imageUrl:` field to paste in the full URL of the image.
|
||||
- [ ] At this point you should try to run the Github Pages deployment script from you fork using Github Actions to test if nothing is breaking. This leverages the [test.js script of the code](https://github.com/web3privacy/data/blob/main/utils/test.js)and will flag any issues and show you which yaml file has an error in it. Allowing you to fix any error prior to merging your Pull Request with the main branch of the codebase.
|
||||
- [ ] If all looks good, all new persons added and their respective images, then push the Pull Request to the maintainers.
|
||||
|
||||
### Part 4: Refreshing data and synching
|
||||
- [ ] Once the PR is merged, verify there are no issues within the Github Pages deployment. To do this visit the Actions page and see if any recent Actions have failed (red circle indicates this).
|
||||
- [ ] Request that the /data maintainer runs the [W3PN data refresh Action](https://github.com/web3privacy/data/actions/workflows/data-refresh.yml)
|
||||
- [ ] Request that the /data maintainer runs the [sync Action](https://github.com/web3privacy/data/actions/workflows/sync.yml)
|
||||
- [ ] Check the event listed in visible on data.web3privacy.info and that images and thumbs have been properly generated by scripts
|
||||
|
||||
### Tips & Tooling
|
||||
- One good practice would be to first copy a person entry and then replacing the relevant information within with the new person data and renaming the yaml file (or use the example satoshi enty in this guide)
|
||||
- CAUTION: respect the indentation of the data entries in the yaml files - this is especially relevant for the `refs` field which has sub-categories which each need to have two spaces outwards from where the `refs` field is (see example below)
|
||||
- CAUTION: if the `country` data field does not follow the [ISO-3166-1 Alpha-2 standard](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) the tests will fail - [see events.js within the web codebase for full list of countries](https://github.com/web3privacy/web/blob/main/src/lib/events.js)
|
||||
- CAUTION: if the `country` data field is two CAPITALISED letters the tests will fail - **only use lowercase for country codes**
|
||||
- CAUTION: data within `refs` data field does not need the http://domain.com/ section, only the handle or username of the person (exception to this is the `email` sub-category)
|
||||
- KNOWN BUG: within the `caption` field you can add URL hyperlinks using markdown, but due to an issue with YAML parsing the url cannot contain certain characters such as `-` this bug has been [reported in the following issue in the repository](https://github.com/web3privacy/data/issues/12)
|
||||
|
||||
### Part 3: Testing
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
-
|
||||
-
|
||||
-
|
||||
- Ask in W3PN chats for support or help
|
||||
|
||||
### Example of a complete person entry (ficticious person)
|
||||
```
|
||||
name: Some Anon
|
||||
nickname: anon
|
||||
caption: Chief Privacy Officer at [noneofyourbusiness](https://domain.lol)
|
||||
country: is
|
||||
refs:
|
||||
twitter: web3privacy
|
||||
github: web3privacy
|
||||
linkedin: someanon
|
||||
bsky: web3privacy
|
||||
matrix: matrix.web3privacy.info
|
||||
email: nicetryspammers@web3privacy.info
|
||||
imageUrl: https://upload.wikimedia.org/wikipedia/en/3/34/RickAstleyNeverGonnaGiveYouUp7InchSingleCover.jpg
|
||||
```
|
||||
|
||||
|
||||
### External resources
|
||||
|
||||
[Github Pages Documentation](https://docs.github.com/en/pages)
|
||||
|
||||
[Example PR of adding a new speaker to Data repository](https://github.com/web3privacy/data/pull/24)
|
||||
|
|
|
|||
52
src/content/docs/contributors/contributor-guide-template.md
Normal file
52
src/content/docs/contributors/contributor-guide-template.md
Normal file
|
|
@ -0,0 +1,52 @@
|
|||
---
|
||||
title: This field is required and must always be between the header section between three lines
|
||||
---
|
||||
|
||||
`WORK IN PROGRESS`
|
||||
|
||||
## Preamble
|
||||
|
||||
|
||||
#### Quick-reference:
|
||||
[https://github.com/web3privacy/REPOSITORY](https://github.com/web3privacy/REPOSITORY)
|
||||
|
||||
## Pre-requisites
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
|
||||
## Step-by-step Guide
|
||||
|
||||
### Part 1: Setup
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
### Part 2: Commits
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
### Part 3: Testing
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
### Tips & Tooling
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
### Troubleshooting
|
||||
- Ask in W3PN chats for support or help
|
||||
-
|
||||
-
|
||||
|
||||
### External resources
|
||||
|
||||
[Github Pages Documentation](https://docs.github.com/en/pages)
|
||||
63
src/content/docs/contributors/gen-img-front-end.md
Normal file
63
src/content/docs/contributors/gen-img-front-end.md
Normal file
|
|
@ -0,0 +1,63 @@
|
|||
---
|
||||
title: Using the gen-img front-end to generate speaker images / event collateral
|
||||
---
|
||||
|
||||
`WORK IN PROGRESS`
|
||||
|
||||
## Preamble
|
||||
|
||||
|
||||
#### Quick-reference:
|
||||
[https://github.com/web3privacy/web](https://github.com/web3privacy/web)
|
||||
|
||||
[gen-img frontend](https://web3privacy.info/gen/event/)
|
||||
|
||||
[gen-img background source](https://github.com/web3privacy/web/tree/main/public/gen-img/events)
|
||||
|
||||
|
||||
## Pre-requisites
|
||||
- [ ] Have a Github account to create a PR in this repository[https://github.com/web3privacy/data](https://github.com/web3privacy/data)
|
||||
- [ ] Have a background image to upload to /web (or use one already within the front-end selector)
|
||||
|
||||
|
||||
## Step-by-step Guide
|
||||
|
||||
### Part 1: Setup
|
||||
- [ ] Sign in to Github and go to the [Data repository](https://github.com/web3privacy/web)
|
||||
- [ ] Make a fork of the Data repository, and proceed to make the edits in your fork
|
||||
- [ ] Collect the following information for the new event: date, location, lead person(s), registration link, some of the confirmed speakers
|
||||
- [ ]
|
||||
|
||||
### Part 2: Commits
|
||||
- [ ] Images for events are similar but require extra steps (see below) story which also begins with Data respoitory. Images for events need to be uploaded to /data/src/events/_images in 4 different image sizes. To aid for the creation of these images a javascript script was written with the Web repository which can be used from the frontend here: https://web3privacy.info/gen/event/
|
||||
- [ ] To be able to create easily the 4 formats of images, you must first upload a base image to the folder and then add it to the svelte function...
|
||||
https://github.com/web3privacy/web/tree/main/public/gen-img/events
|
||||
- [ ] Generate the 4 different format images for the event using the [gen-img frontend](https://web3privacy.info/gen/event/)
|
||||
- [ ] navigate to the gen-img page for the event by clicking on the image or use the drop-down menu
|
||||
- [ ] right-click to 'save image as' for the 5 formats needed: square, wide-square, wide, poster, poster-simple. (Please note: the speaker image is not necessary at this time, only useful to generate marketing collateral)
|
||||
- [ ] Upload those images to your fork within the _images folder noted in last step of Part 2
|
||||
- [ ] Double check the content and images are there, then you can create a Pull Request from your fork into the main /data repository.
|
||||
|
||||
### Part 3: Testing
|
||||
- [ ] Once the PR is merged, verify there are no issues within the Github Pages deployment. To do this visit the Actions page and see if any recent Actions have failed (red circle indicates this).
|
||||
- [ ] Request that the /data maintainer runs the [W3PN data refresh Action](https://github.com/web3privacy/data/actions/workflows/data-refresh.yml)
|
||||
- [ ] Request that the /data maintainer runs the [sync Action](https://github.com/web3privacy/data/actions/workflows/sync.yml)
|
||||
- [ ] Check the event listed in visible on data.web3privacy.info and that images and thumbs have been properly generated by scripts
|
||||
- [ ] Wait 6 hours for the automated scripts within the /web code base to activate and scrape the appropriate data from data.web3privacy.info
|
||||
- [ ] navigate to the events section of the website and verify all is correct: [https://web3privacy.info/events](https://web3privacy.info/events)
|
||||
|
||||
|
||||
### Tips & Tooling
|
||||
- [ ] [https://web3privacy.info/gen/event](https://web3privacy.info/gen/event)
|
||||
- [ ] [https://github.com/web3privacy/web/tree/main/public/gen-img/events](https://github.com/web3privacy/web/tree/main/public/gen-img/events)
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
### Troubleshooting
|
||||
- Ask in W3PN chats for support or help
|
||||
-
|
||||
-
|
||||
|
||||
### External resources
|
||||
|
||||
[Example PR of adding an image to the Data repository](https://github.com/web3privacy)
|
||||
Loading…
Reference in a new issue