diff --git a/students/KevinEyo1/knowledge.md b/students/KevinEyo1/knowledge.md index 817019e66..e864622d3 100644 --- a/students/KevinEyo1/knowledge.md +++ b/students/KevinEyo1/knowledge.md @@ -1,6 +1,22 @@ -### Tool/Technology 1 +### Summary of Key Contributions -List the aspects you learned, and the resources you used to learn them, and a brief summary of each resource. +Worked on adding [Software Project Documentation](https://github.com/MarkBind/markbind/pull/2400) template to MarkBind, allowing for users to have a starting point for using MarkBind in their project documentation. + +Researched into possible integrations of [Bun](https://github.com/MarkBind/markbind/issues/2448) and [Bootstrap v5.2 and v5.3](https://github.com/MarkBind/markbind/issues/2359) into MarkBind, to determine the value and feasibility of these integrations. + +Worked on [customizing list icons](https://github.com/MarkBind/markbind/pull/2454), such that icons for list items can be customized to apply to the current item only instead of default inheritance to future items. + +Worked largely on DevOps side of MarkBind, utilizing GitHub Actions and workflows to handle automation of tasks. These tasks include checking for [commit messages in PR descriptions](https://github.com/MarkBind/markbind/pull/2429), [SEMVER impact labels](https://github.com/MarkBind/markbind/pull/2470), [reminding adding of new contributors to contributor list](https://github.com/MarkBind/markbind/pull/2484). + +[Researched](https://github.com/MarkBind/markbind/issues/2140) and [implemented](https://github.com/MarkBind/markbind/pull/2523) the use of DangerJS to automate checking of changes coupling of implementation files to test or documentation files, to ensure that any changes to the repository is properly documented and tested. + +Researched into the implementation of automating [unassigning of assigned users to issues](https://github.com/MarkBind/markbind/issues/2495) after a certain period of inactivity. + +Researched into [common security practices](https://github.com/MarkBind/markbind/issues/2488) for GitHub Actions, and [implementing these practices](https://github.com/MarkBind/markbind/pull/2510) into the MarkBind repository. These practices are also [documented](https://github.com/MarkBind/markbind/pull/2528) for future contributors to the project. + +### MarkBind codebase + +Learned the underlying workings and how different parts of the codebase are linked together to provide MarkBind's functionalities. From the parser to the renderer, and the different plugins that can be used to extend MarkBind's capabilities. Learned how to implement new features, adding relevant test and documentation to ensure that the codebase is maintainable and modifiable. ### GitHub Actions @@ -12,18 +28,207 @@ Learned how GitHub Actions fits into the development workflow, and how to use it - **Resource**: [GitHub Actions Workflow Syntax](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) - **Summary**: GitHub Actions uses YAML syntax to define the events, jobs, and steps that make up your workflow. You can create a custom workflow or use a starter workflow template to get started. -### Node package structure +- **Resource**: [GITHUB_TOKEN](https://docs.github.com/en/actions/security-guides/automatic-token-authentication) +- **Summary**: The GITHUB_TOKEN is a GitHub Actions token that is automatically generated by GitHub and used to authenticate in a workflow run. It is scoped to the repository that contains the workflow file, and can be used to perform read and write operations on the repository. It is automatically available to your workflow and does not need to be stored as a secret. + +Learned yaml and bash for creation of workflows. + +- **Resource**: [YAML Syntax](https://www.cloudbees.com/blog/yaml-tutorial-everything-you-need-get-started) +- **Summary**: YAML is a human-readable data serialization standard that can be used in conjunction with all programming languages and is often used to write configuration files. It can also be used in workflows to define the structure of the workflow, including the events, jobs, and steps that make up the workflow. + +- **Resource**: [Bash Scripting](https://devhints.io/bash) +- **Summary**: Bash is a Unix shell and command language written by Brian Fox for the GNU Project as a free software replacement for the Bourne shell. It has been distributed widely as the shell for the GNU operating system and as a default shell on Linux and OS X. + +- **Resource**: [Bash Parameter Expansion](https://web.archive.org/web/20230408142504/https://wiki.bash-hackers.org/syntax/pe) +- **Summary**: Parameter expansion is a way to manipulate variables in Bash. It is a form of variable substitution that allows for the manipulation of variables in various ways. + +Learned how to use other actions in workflows, such as the `actions/checkout` action to check out a repository onto the runner, allowing subsequent steps to execute operations on the checked-out repository. + +- **Resource**: [GitHub Marketplace](https://github.com/marketplace) +- **Summary**: The GitHub Marketplace is a collection of actions that can be used in your workflows. You can search for actions by category, language, or other criteria, and use them in your workflows to automate tasks. + +Learned how to use DangerJS to aid with workflows. +- **Resource**: [DangerJS](https://danger.systems/js/) +- **Summary**: Danger runs during your CI process, and helps with automating common code review chores. This provides another layer of automation over the code review process, ensuring that all changes are properly documented and tested. -### Plugins +**When to create new workflows (outside of modifiability)** +Although keeping multiple jobs within the same workflow file is possible, sometimes it may be better not to. Jobs are run based on event triggers such as pull requests etc, but you must add it to the top. This meant that if you had multiple jobs in the same workflow file, they would all run when the event trigger was activated. If you wanted a trigger to only trigger a specific job, you would need to add a check to exclude all other jobs from that trigger. +Pull request trigger by default has the types `opened`, `synchronize`, and `reopened`. + +**Testing and debugging workflows** +This can be done locally with the help of Docker and act. + +Benefits of local testing: +Fast Feedback - Avoid commit/push every time you want to test out the changes. + +- **Resource**: [Act Usage](https://nektosact.com/usage/index.html) +- **Summary**: Act reads in your GitHub Actions from .github/workflows/ and determines the set of actions that need to be run. It uses the Docker API to either pull or build the necessary images, as defined in your workflow files and finally determines the execution path based on the dependencies that were defined. Once it has the execution path, it then uses the Docker API to run containers for each action based on the images prepared earlier. + +- **Resource**: [Docker Docs](https://docs.docker.com/get-started/overview/) +- **Summary**: + +Steps (PR): +1. Download act and Docker. +1. Start up Docker daemon. +1. Create a JSON file with the appropriate PR file structure (can use python script to generate it). +1. Run `act pull_request -j specific-job -e pr-event.json` to run a specific job on the PR event environment. + +#### Keywords +`uses`: +Can be used to reference an action in the same repository, a public repository, or a published Docker container image. The `uses` keyword can also be used to reference an action in a private repository by specifying the repository using the `repository` keyword. + +`env`: +It is best to avoid having expressions `${{ }}` in _run_ portion of a step. Instead, `env` allows defining of variables that store the expression. + +`awk` : +Can be used to extract a section of body, from a line containing `START` to a line containing `END` (inclusive of full line). +`section=$(echo "$body" | awk '/START/,/END/')` + + +#### Use of third-party actions +- **Resource**: [GitHub Actions Marketplace](https://github.com/marketplace?type=actions) +- **Summary**: The GitHub Actions Marketplace is a collection of actions that can be used in your workflows. You can search for actions by category, language, or other criteria, and use them in your workflows to automate tasks. + +Useful actions: +| Action | Description | +| ------ | ----------- | +| `actions/checkout@v3` | Check out a repository onto the runner, allowing subsequent steps to execute operations on the checked-out repository, i.e. gaining access to the repository's code. | +| `actions/github-script@v7` | Run a script in the GitHub Actions environment using the GitHub CLI. Refer to [here](https://octokit.github.io/rest.js/v20) | +| `actions/setup-node@v3` | Set up a Node.js environment for use in workflows. | +| `actions/stale` | Close stale issues and pull requests. | +| `boundfoxstudios/action-unassign-contributor-after-days-of-inactivity` | Automatically unassign user from issues after a certain period of inactivity. | + +#### Extra information about how stale and unassign actions work in the context of MarkBind + +The definition of inactivity for the GitHub action is any form of history to the issue, be it labeling, comments or references. The action works such that issues and PRs are treated and checked for inactivity separately. This means that any updates done to a PR regarding this issue, will not reset inactivity for the issue. + +How unassign and stale actions work: +1. Stale action adds `Stale` label to issue or PR based on inactivity (default 60 days) +2. Unassign action routinely checks for this `Stale` label, then checks whether it's been a set amount of days after the `Stale` label has been added with no other activity (default 7 days) +3. For issues passing the check before, it un-assigns users and removes `Stale` label + +[Reference workflow of real-life example](https://github.com/BoundfoxStudios/fairy-tale-defender/blob/develop/.github/workflows/project-management.yml#L105) + +##### Solution using unassign and stale actions + +Add the `Stale` label after 6 days and ping a reminder, then have the [unassign-contributor-after-days-of-inactivity](https://github.com/marketplace/actions/unassign-contributor-after-days-of-inactivity) run 1 day after. +It can also only check on issues that are actually assigned to someone, so that theres no redundancy. +**Limitations:** +1. Any changes in PR regarding issue will not reset inactivity of issue, meaning if discussion and updates are done on the PR instead of the issue, the issue risks being `Stale` and the user being unassigned despite them actively working on the PR. +2. It can ping a general reminder (without resetting the inactivity) but it cannot ping the user directly with `@username` in the reminder due to how the code is written. It is possible to separately ping the user in another comment but that will cause a reset in inactivity. This means slightly lower visibility for the reminder. + +##### Improvements for limitation 1 + +Building on unassign action, which at some point it might be better off just building our own unassign action for better integration and control +**Check corresponding PR (requires more implementation)** +Add additional check before setting `Stale` label to check if corresponding PR has history. +This can be done through checking the list of open PRs and their descriptions whether it mentions the issue. It can also be done through looking at the issue’s history, for PRs that mention it, then checking the history of those PRs. This should be quite manageable since the number of open PRs at any point of time is still relatively low for Markbind’s scale. + +**Check corresponding issue (requires more implementation)** +On any activity in PRs, check description to find issues linked to the PR, so activity on PR can be translated to activity on the issue as well by posting a comment on the corresponding issue or something of that nature. This might require checking for a specific issue that has the user assigned to avoid commenting on relevant but not directly linked issues, if the PR has multiple relevant issues. We can also only call it on commits instead of any activity, so as to avoid over-polluting the issue with comments. + +##### Improvements for limitation 2 + +**Ping after unassign** +Same as before, add `Stale` level after 6 days, but don't need to ping the user, wait until unassign 1 day after, then ping the user that they have been unassigned and if they are still working on it, ask them to reassign themselves. This would likely fit better with a longer timeline. +This solves the visibility problem as it can directly ping the user as resetting the inactivity after the user has been unassigned wouldn't matter. + +**Implement our own stale action (requires more implementation)** +Implement a simplified version of stale action that now allows pinging of user before applying the `Stale` label. + + +#### pull_request_target +Due to security reasons, for permissions given to `GITHUB_TOKEN`, the maximum access for pull requests from public forked repositories is restricted to only read, so it is not possible to add labels since there is no write access. GitHub introduced the `pull_request_target` event that will bypass this restriction and give the token write access. +Pros: +1. It allows labelling of PR +1. Increased security as base branch workflows can be trusted, protecting job from running modified and malicious workflows +Cons: +1. It can only run on `pull_request` events and not `pull_request_review` events which means need to run on PR merge rather than on PR approved. +1. This event runs in the context of the base of the pull request, rather than in the context of the merge commit, as the `pull_request` event does. This could lead to security vulnerabilities if scripts run are not properly checked for malicious code. +Can be aided by seeking approval before running the job, refer to [change repo settings](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#controlling-changes-from-forks-to-workflows-in-public-repositories) + +##### Alternative implementations +[Workaround](https://stackoverflow.com/questions/67247752/how-to-use-secret-in-pull-request-review-similar-to-pull-request-target) +Pros: this can allow for still triggering on PR approved +Cons: immensely complicates the workflow + +Personal Access Token (PAT) +Create a PAT with the necessary permissions and add it to your repository's secrets. Then, modify the workflow to use this secret instead of the `GITHUB_TOKEN`. +Pros: this can allow for still triggering on PR approved +Cons: exposes your repository to risks if the forked code can access the token + +### GitHub Actions Security +- **Resource**: [Using pull_request_target](https://dev.to/suzukishunsuke/secure-github-actions-by-pullrequesttarget-641) +- **Resource**: [Security and Cheatsheet](https://blog.gitguardian.com/github-actions-security-cheat-sheet/) +- **Resource**: [Security Lab](https://securitylab.github.com/research/github-actions-preventing-pwn-requests/) + +**Specific version tags** +When using third-party actions, pin the version with a commit hash rather than a tag to shield your workflow from potential supply-chain compromise, since tags can be adjusted to a malicious codebase state but commit hashes provide immutability. +This can be done by going to the codebase for the specific tag version and looking for the latest commit of the version desired and copying the commit’s full SHA from the url link. +Use: +`uses: someperson/post-issue@f054a8b5c1271c37293245628f1cae047eff08c9` +Instead of: +`uses: someperson/post-issue@v7` +Downside is that the updates must be done by updating the commit hash instead of it being done automatically through moving the tag to a new release. +This can be solved by using tools like Dependabot or Renovatebot by adding a comment of the version used, enabling automated dependency updates. Tools like StepSecurity can also be used. + +**Minimally scoped credentials** +Every credential used in the workflow should have the minimum required permissions to execute the job. +In particular, use the ‘permissions’ key to make sure the GITHUB_TOKEN is configured with the least privileges for each job. +`permissions` can be restricted at the repo, workflow or job level. +**Environment variables**, like `${{ secrets.GITHUB_TOKEN }}`, should be limited by scope, and should be declared at the step level when possible. + +**Pull_request_target** (must be used for write access if PR is from forked repo) +Do not use actions/checkout with this as it can give write permission and secrets access to untrusted code. Any building step, script execution, or even action call could be used to compromise the entire repository. This can be fixed by adding code to ensure that the code being checked out belongs to the base branch, which would also be limiting since the code checked out is not up to date for the PR. +This can be done using: +``` +- uses: actions/checkout@v4 + with: + ref: ${{ github.base_ref }} +``` +Triggers workflows based on the latest commit of the pull request's base branch. +Even if workflow files are modified or deleted on feature branches, workflows on the default branch aren't affected so you can prevent malicious code from being executed in CI without code review. +Another solution that allows `pull_request_target` with `actions/checkout` used on the PR branch, is to add an additional step of running workflow only on approval by trusted users, such that the trusted user has to check the changes in the code from the PR to ensure there is no malicious code before running the workflow. + +**Untrusted input** +Don't directly reference values you do not control, such as `echo “${{github.event.pull_request.title}}”`, since it can contain malicious code and lead to an injection attack. +Instead use an action with arguments (recommended): +``` +uses: fakeaction/printtitle@v3 +with: +title: ${{ github.event.pull_request.title }} +``` +Or bind the value to an intermediate environment variable: +``` +env: +PR_TITLE: ${{ github.event.pull_request.title }} +run: | +echo “$PR_TITLE” +``` + +Use [**OIDC**](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) and respective Secrets Manager for access to cloud providers instead of using secrets. +Use [**GitHub Secrets**](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) to store keys securely and reference in workflows using `${{}}`. +Can use [**GitGuardian Shield**](https://github.com/GitGuardian/ggshield-action?ref=blog.gitguardian.com) to help with scanning for security vulnerabilities. ### Typescript +Typescript is a superset of JavaScript that adds static typing to the language. By manipulating variables and functions, Typescript can help catch errors before they occur. +| Syntax | Name | Feature | +| ------ | ---- | ------- | +| `?` | Optional chaining operator | variable returns undefined if doesn't exist. Also used for optional function parameters or class properties | +| `??` | Nullish coalescing operator | returns the right-hand operand when the left-hand operand is null or undefined. | +| `!` | Non-null assertion operator | variable is not null or undefined, only used if you are sure that value will exist. | + -### MarkBind Lists Implementation +### Process of upgrading dependencies and packages +MarkBind uses a monorepo structure, which means that multiple packages are contained in a single repository. +The process of upgrading dependencies and packages in MarkBind involves the following steps: -### General MarkBind Implementation Details +1. **Checking current versions**: Check the current versions of the dependencies and packages in the project. This can be done by looking at the `package.json` file for each project. The command `npm ls package_name` will output which packages are using what versions. +2. **Review changelog and documentation**: Review the changelog and documentation for the dependencies and packages to see what changes have been made in the new versions. +3. **Upgrade dependencies and packages**: Update the relevant `package.json` file or the root one for dependencies across all packages, then run `npm run setup` \ No newline at end of file diff --git a/students/KevinEyo1/progress.md b/students/KevinEyo1/progress.md index 7670af011..ed73b1e00 100644 --- a/students/KevinEyo1/progress.md +++ b/students/KevinEyo1/progress.md @@ -1,13 +1,44 @@ ### MarkBind - | Week | Achievements | | ---- | ------------ | -| 2 | Authored PR: [MarkBind Template for Software Project Documentation#2400]() | -| 4 | Authored PR: [Enhance search performance of algolia plugin #2406]() | -| 5 | Merged PR: [Enhance search performance of algolia plugin #2406]() | -| 6 | Authored PR: [Utilize GitHub Actions to aid checking of commit message #2429]() | -| 6 | Merged PR: [Utilize GitHub Actions to aid checking of commit message #2429]() | -| 6 | Authored PR: [Upgrade simple-git version #2439]() | -| 6 | Merged PR: [Upgrade simple-git version #2439]() | -| 6 | Authored PR: [UG > PagNav: Misleading sentence #2440]() | \ No newline at end of file +| 2 | Authored PR: [MarkBind Template for Software Project Documentation#2400](https://github.com/MarkBind/markbind/pull/2400) | +| 4 | Authored PR: [Enhance search performance of algolia plugin #2406](https://github.com/MarkBind/markbind/pull/2406) | +| 5 | Merged PR: [Enhance search performance of algolia plugin #2406](https://github.com/MarkBind/markbind/pull/2406) | +| 6 | Authored PR: [Utilize GitHub Actions to aid checking of commit message #2429](https://github.com/MarkBind/markbind/pull/2429) | +| 6 | Merged PR: [Utilize GitHub Actions to aid checking of commit message #2429](https://github.com/MarkBind/markbind/pull/2429) | +| 6 | Authored PR: [Upgrade simple-git version #2439](https://github.com/MarkBind/markbind/pull/2439) | +| 6 | Merged PR: [Upgrade simple-git version #2439](https://github.com/MarkBind/markbind/pull/2439) | +| 6 | Authored PR: [UG > PagNav: Misleading sentence #2440](https://github.com/MarkBind/markbind/pull/2440) | +| 7 | Merged PR: [UG > PagNav: Misleading sentence #2440](https://github.com/MarkBind/markbind/pull/2440) | +| 7 | Submitted Issue: [Fancylists to package MarkBind's current and future list features #2458](https://github.com/MarkBind/markbind/issues/2458) | +| 8 | Authored PR: [Customizing list icons: give a way to apply to current item only #2454](https://github.com/MarkBind/markbind/pull/2454) | +| 8 | Submitted Issue: [Utilize GitHub Actions to check for SEMVER impact label #2464](https://github.com/MarkBind/markbind/issues/2464) | +| 8 | Authored PR: [Utilize GitHub Actions to check for SEMVER impact label #2464](https://github.com/MarkBind/markbind/pull/2470) | +| 8 | Researched Issue: [Bootstrap migration tracker #2359](https://github.com/MarkBind/markbind/issues/2359) | +| 9 | Reviewed PR: [MarkBind Template for Student Portfolio #2398](https://github.com/MarkBind/markbind/pull/2398) | +| 9 | Researched Issue: [[Feature request] Tag (keywortd) support #2187](https://github.com/MarkBind/markbind/issues/2187) | +| 10 | Researched Issue: [Utilize GitHub Actions to check for SEMVER impact label #2464](https://github.com/MarkBind/markbind/issues/2464) | +| 10 | Merged PR: [Utilize GitHub Actions to check for SEMVER impact label #2464](https://github.com/MarkBind/markbind/pull/2470) | +| 10 | Submitted Issue: [Reusable workflow repo for all repos under organisation #2479](https://github.com/MarkBind/markbind/issues/2479) | +| 10 | Merged PR: [MarkBind Template for Software Project Documentation#2400](https://github.com/MarkBind/markbind/pull/2400) | +| 10 | Authored PR: [Add a reminder when contributor is new to ping all contributor bot #2484](https://github.com/MarkBind/markbind/pull/2484) | +| 11 | Submitted Issue: [Improve security of GitHub Actions workflows #2488](https://github.com/MarkBind/markbind/issues/2488) | +| 11 | Researched Issue: [Improve security of GitHub Actions workflows #2488](https://github.com/MarkBind/markbind/issues/2488) | +| 11 | Researched Issue: [Explore using Bun for testing and setup #2448](https://github.com/MarkBind/markbind/issues/2448) | +| 11 | Merged PR: [Customizing list icons: give a way to apply to current item only #2454](https://github.com/MarkBind/markbind/pull/2454) | +| 11 | Researched Issue: [Utilize GitHub Action to aid PR review #2140](https://github.com/MarkBind/markbind/issues/2140) | +| 12 | Authored PR: [Improve security of GitHub Actions workflows #2510](https://github.com/MarkBind/markbind/pull/2510) | +| 12 | Authored PR: [UG: images appear in two places #2514](https://github.com/MarkBind/markbind/pull/2514) | +| 12 | Merged PR: [Add a reminder when contributor is new to ping all contributor bot #2484](https://github.com/MarkBind/markbind/pull/2484) | +| 12 | Merged PR: [Improve security of GitHub Actions workflows #2510](https://github.com/MarkBind/markbind/pull/2510) | +| 12 | Researched Issue: [Add github action to automatically unassign issues after a certain period of inactivity #2495](https://github.com/MarkBind/markbind/issues/2495) | +| 12 | Merged PR: [UG: images appear in two places #2514](https://github.com/MarkBind/markbind/pull/2514) | +| 13 | Authored PR: [Fix workflow file deploy-docs #2521](https://github.com/MarkBind/markbind/pull/2521) | +| 13 | Merged PR: [Fix workflow file deploy-docs #2521](https://github.com/MarkBind/markbind/pull/2521) | +| 13 | Researched Issue: [Add github action to automatically unassign issues after a certain period of inactivity #2495](https://github.com/MarkBind/markbind/issues/2495) | +| 13 | Authored PR: [Using DangerJS to check changes coupling of implementation files to test or documentation files #2523](https://github.com/MarkBind/markbind/pull/2523) | +| 13 | Submitted Issue: [Add documentation for workflow security for GitHub Actions #2527](https://github.com/MarkBind/markbind/issues/2527) | +| 13 | Authored PR: [Add documentation regarding security practices for github actions #2528](https://github.com/MarkBind/markbind/pull/2528) | +| 13 | Merged PR: [Using DangerJS to check changes coupling of implementation files to test or documentation files #2523](https://github.com/MarkBind/markbind/pull/2523) | +| 13 | Merged PR: [Add documentation regarding security practices for github actions #2528](https://github.com/MarkBind/markbind/pull/2528) | \ No newline at end of file