{title}
12 |
13 |
-
30 | { resources && resources.map((resource) => (
31 |
-
32 |
33 | {resource.title} 34 |
35 | )
36 | ) }
37 |
21 |
29 |
22 |
23 |
27 |
28 |
31 |
32 |
34 | {post.title}
32 |
By userId: {post.userId}
33 |
37 |
39 | {post.body}
38 |Contributors
17 |
21 |
24 | Guides
22 |
27 |
30 | External Resources
28 |
9 |
17 |
18 |
19 |
76 |
--------------------------------------------------------------------------------
/.github/workflows/adds-hacktoberfest-label.yml:
--------------------------------------------------------------------------------
1 | # If a PR is opened within October, then add Hacktoberfest label
2 | # Also supports other challenges, like NovemberSoftwareChallenge and 24PR-December
3 | name: 🎃 Add Hacktoberfest Label
4 |
5 | on:
6 | pull_request_target:
7 | types:
8 | - opened
9 |
10 | permissions:
11 | issues: write
12 | pull-requests: write
13 |
14 | jobs:
15 | add-label:
16 | runs-on: ubuntu-latest
17 | steps:
18 | - name: 📆 Check current month
19 | id: check-date
20 | run: |
21 | MONTH=$(date +'%m')
22 | if [[ "$MONTH" == "10" ]]; then
23 | echo "::set-output name=month::october"
24 | elif [[ "$MONTH" == "11" ]]; then
25 | echo "::set-output name=month::november"
26 | elif [[ "$MONTH" == "12" ]]; then
27 | echo "::set-output name=month::december"
28 | else
29 | echo "::set-output name=month::other"
30 | fi
31 | - name: 🏷️ Add labels based on month
32 | uses: actions/github-script@v3
33 | with:
34 | github-token: ${{ secrets.BOT_TOKEN || secrets.GITHUB_TOKEN }}
35 | script: |
36 | let labelsToAdd = [];
37 | switch ("${{ steps.check-date.outputs.month }}") {
38 | case "october":
39 | labelsToAdd.push('hacktoberfest-accepted');
40 | break;
41 | case "november":
42 | labelsToAdd.push('NovemberSoftwareChallenge');
43 | break;
44 | case "december":
45 | labelsToAdd.push('24PR-December');
46 | break;
47 | }
48 | if (labelsToAdd.length) {
49 | github.issues.addLabels({
50 | issue_number: context.issue.number,
51 | owner: context.repo.owner,
52 | repo: context.repo.repo,
53 | labels: labelsToAdd
54 | });
55 | }
56 |
--------------------------------------------------------------------------------
/web/src/components/Header.astro:
--------------------------------------------------------------------------------
1 | ---
2 | import Navigation from '../components/Navigation.astro'
3 | import { SkipLinks } from 'accessible-astro-components'
4 | import { Icon } from 'astro-icon'
5 |
6 | const guides = await Astro.glob('./../pages/guides/*.md');
7 |
8 | ---
9 |
10 |
11 |
16 |
9 |
13 |
10 |
12 | 4 | > TODO: I'm going to make instructions clearer, and add screenshots 5 | 6 | ### 1. Fork the Repository 7 | 8 | - Start by visiting the GitHub page of the repository you want to contribute to. 9 | - In the top-right corner of the page, you'll see a button labeled "Fork". Click it. 10 | - This creates a copy of the repository under your GitHub account. You'll be redirected to your fork. 11 | 12 | 13 | ### 2. Make Changes 14 | 15 | - Browse through the repository files and directories by clicking on them. 16 | - Once you've located the file, click on it to view its contents. 17 | - Click on the pencil icon (it'll be labeled "Edit this file" when you hover over it) in the top-right corner of the file viewer. 18 | - Make your changes to the file in the editor that appears. 19 | 20 | ### 3. Commit the Changes 21 | 22 | - Scroll down to the bottom of the page. You'll see a section titled "Commit changes". 23 | - Enter a short, descriptive title for your changes in the "Commit changes" box. 24 | - Optionally, provide a more detailed description in the larger text box below. 25 | - Ensure the radio button "Create a new branch for this commit and start a pull request." is selected. 26 | - Click on the green "Commit changes" button. 27 | 28 | ### 4. Open a Pull Request (PR) 29 | 30 | - After committing, you'll be taken to a new page titled "Open a pull request". 31 | - GitHub will automatically fill in some details for the PR based on your commit message. 32 | - If you want, edit the title and description of the PR to provide more context or information about your changes. The more detailed and clear you are, the easier it will be for the maintainers. 33 | - Once you're ready, click on the green "Create pull request" button. 34 | 35 | ### 5. Await Feedback 36 | 37 | - The maintainers of the original repository will be notified of your pull request. 38 | - They might provide feedback or ask for changes. Make sure to keep an eye on the PR for any comments or notifications. 39 | - If changes are requested, you can make them directly in your forked repo through the GitHub UI, and they will automatically be added to the open PR. 40 | 41 | ### 6. Celebrate! 42 | 43 | - Once your pull request is approved and merged, you've officially contributed to the project! 44 | -------------------------------------------------------------------------------- /.github/PRIVACY.md: -------------------------------------------------------------------------------- 1 | # Privacy Policy 2 | 3 | ## Our Commitment to Privacy 4 | 5 | We take your privacy seriously. Our primary goal is to be transparent and foster trust. 6 | We believe that you have the right to understand how your information is used and given the power to make informed decisions. 7 | 8 | ## Data We Collect 9 | 10 | The nature of our project means we inherently collect very minimal data: 11 | 12 | First-Party Services 13 | - **Plausible**: The website uses a self-hosted instance Plausible Analytics solely for hit counting. It respects the "Do Not Track" browser setting and does not collect any personal data. Learn more about how Plausible respects user privacy [here](https://plausible.io/privacy-focused-web-analytics). 14 | 15 | Third-Party Services 16 | - **GitHub**: Hosting our project on GitHub might subject you to their privacy practices. We don't have any additional tracking or data collection on top of what GitHub provides. 17 | - **Netlify**: Our website is hosted on Netlify. Any interactions with our site might be subjected to Netlify's privacy policy. 18 | - **CloudFlare**: We use CloudFlare to protect our website from malicious attacks. Any interactions with our site might be subjected to CloudFlare's privacy policy. 19 | 20 | ## No Personal Data Collection 21 | 22 | We promise we don't and won't ever collect personal data from our users. Your privacy is paramount, and we aim to respect it at every level of our project. 23 | 24 | ## Addressing Concerns 25 | 26 | If you have any concerns about privacy or data security, we are here to address them: 27 | 28 | - **Prompt Response**: Reach out to us, and we'll address your concerns as swiftly as possible. 29 | - **Openness to Questions**: Anything unclear? Any part of our setup you're curious about? Ask us. We're committed to clarity and transparency. 30 | - **Feedback Welcomed**: We're always striving to do better. If you see areas where we can improve in terms of privacy or have suggestions, we're all ears. 31 | 32 | ## Your Rights 33 | 34 | You have the right to: 35 | 36 | - **Ask Questions**: We're here to clarify, explain, and justify any of our practices. 37 | - **Request Removal**: If you ever feel your privacy might have been compromised or just want to ensure your data is not stored, let us know. We'll act promptly. 38 | 39 | Your trust is important to us, and we are committed to protecting your privacy and data at all times. 40 | -------------------------------------------------------------------------------- /guides/open-source-for-businesses.md: -------------------------------------------------------------------------------- 1 | 2 | # Open Source for Business 3 | 4 | Wish you could do more open source work at your day job? 5 | The following article should give you some pointers that you can use to help you explain the business benefits of open source to your company or boss. 6 | 7 | ### Key Benefits 8 | - Attract a higher calibre of talent 9 | - Improve reputation and brand recognition among development circles 10 | - Reflects well on you from a technological and ethical perspective 11 | - Great experience for junior developers to contribute and learn 12 | - Opportunity to showcase and share your tech standards 13 | - Cost saving potential, as once a project is off the ground, external contributors often do the bulk of maintenance and improvements 14 | - Helps you innovate quicker, the open source code and content tends to move a lot faster than corporate and propriety alternatives 15 | 16 | ### Key Disadvantages / Considerations 17 | - Comprehensive review process needs to be in place, to ensure that any content you put out is correct, ethical and able to be shared publicly 18 | - Time constraints - This will take a bit of time to get setup and going 19 | 20 | ### Case Studies 21 | - [GCHQ](https://github.com/gchq) - They've made a number of their internal tools open source (like the famous [CyberChef](https://github.com/gchq/CyberChef)), now the majority of maintenance is done by the community 22 | - [ElseWhen](https://github.com/elsewhencode/) - A small digital consultancy, which published [project-guidelines](https://github.com/elsewhencode/project-guidelines) helping them get a reputation for good coding standards 23 | - [Novu](https://novu.co/) - They [write great posts](https://dev.to/novu) on dev.to, to share knowledge 24 | - [React](https://github.com/facebook/react) - Started by Facebook, React.JS has now seen over 1000 community contributors, helping with bug fixes, docs and feature development 25 | - RedHat - A multinational company who open source the majority of their offerings, were valued at $34b (by IBM, as of 2019) 26 | 27 | ### Methods 28 | - A GitHub organisation where employees can collate and share public components, utils and knowledge 29 | - By sponsoring existing projects, which are either up and coming, or that you rely upon to do our job 30 | - By contributing to existing projects, when the opportunity to do so arises 31 | - Writing blog posts on a developer-focused site, like Dev.to 32 | 33 | -------------------------------------------------------------------------------- /web/src/components/Hero.astro: -------------------------------------------------------------------------------- 1 | --- 2 | import { Icon } from 'astro-icon' 3 | --- 4 | 5 |
7 |
40 |
8 | 
38 |
39 |
9 |
10 |
14 |
37 |
10 |
11 | Git into
12 | Open Source
13 |
14 | 12 | Open Source
15 |
23 | Tools, guides and resources to help you kickstart your open source journey
16 |
17 | Not sure where to start? Why not submit a PR adding your username to
18 |
19 | git-in-here.yml
20 | !
21 |
24 |
25 |
36 |
38 |
21 |
28 | Blog
22 |23 | An example of a blog with dynamic content fetched from JSONPlaceholder using the title, body and userId. The Accessible Astro Card Component is used here to display al the posts. 26 |
27 |
31 |
58 | Post {page.start + 1} through {page.end + 1} of {page.total} total posts
32 |-
33 | {
34 | page.data.map((post) => (
35 |
-
36 |
41 | {post.body} 42 | 43 |
44 | ))
45 | }
46 |
48 |
57 | 21 | > TODO: I'm going to make instructions clearer, and add screenshots 22 | 23 | ### 1. Fork the Repository 24 | 25 | - Start by visiting the GitHub page of the repository you want to contribute to. 26 | - In the top-right corner of the page, you'll see a button labeled "Fork". Click it. 27 | - This creates a copy of the repository under your GitHub account. You'll be redirected to your fork. 28 | 29 | 30 | ### 2. Make Changes 31 | 32 | - Browse through the repository files and directories by clicking on them. 33 | - Once you've located the file, click on it to view its contents. 34 | - Click on the pencil icon (it'll be labeled "Edit this file" when you hover over it) in the top-right corner of the file viewer. 35 | - Make your changes to the file in the editor that appears. 36 | 37 | ### 3. Commit the Changes 38 | 39 | - Scroll down to the bottom of the page. You'll see a section titled "Commit changes". 40 | - Enter a short, descriptive title for your changes in the "Commit changes" box. 41 | - Optionally, provide a more detailed description in the larger text box below. 42 | - Ensure the radio button "Create a new branch for this commit and start a pull request." is selected. 43 | - Click on the green "Commit changes" button. 44 | 45 | ### 4. Open a Pull Request (PR) 46 | 47 | - After committing, you'll be taken to a new page titled "Open a pull request". 48 | - GitHub will automatically fill in some details for the PR based on your commit message. 49 | - If you want, edit the title and description of the PR to provide more context or information about your changes. The more detailed and clear you are, the easier it will be for the maintainers. 50 | - Once you're ready, click on the green "Create pull request" button. 51 | 52 | ### 5. Await Feedback 53 | 54 | - The maintainers of the original repository will be notified of your pull request. 55 | - They might provide feedback or ask for changes. Make sure to keep an eye on the PR for any comments or notifications. 56 | - If changes are requested, you can make them directly in your forked repo through the GitHub UI, and they will automatically be added to the open PR. 57 | 58 | ### 6. Celebrate! 59 | 60 | - Once your pull request is approved and merged, you've officially contributed to the project! 61 | 62 | 63 | 71 | -------------------------------------------------------------------------------- /web/src/pages/guides/open-source-for-businesses.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: ../../layouts/MarkdownLayout.astro 3 | title: Open Source for Businesses 4 | description: See all the ways embracing open source can benefit your company. 5 | author: None 6 | icon: 'ic:round-business-center' 7 | tags: 'None' 8 | index: '4' 9 | created: None 10 | updated: 2023-10-08 11 | --- 12 | 13 | 17 | 18 | 19 | # Open Source for Business 20 | 21 | Wish you could do more open source work at your day job? 22 | The following article should give you some pointers that you can use to help you explain the business benefits of open source to your company or boss. 23 | 24 | ### Key Benefits 25 | - Attract a higher calibre of talent 26 | - Improve reputation and brand recognition among development circles 27 | - Reflects well on you from a technological and ethical perspective 28 | - Great experience for junior developers to contribute and learn 29 | - Opportunity to showcase and share your tech standards 30 | - Cost saving potential, as once a project is off the ground, external contributors often do the bulk of maintenance and improvements 31 | - Helps you innovate quicker, the open source code and content tends to move a lot faster than corporate and propriety alternatives 32 | 33 | ### Key Disadvantages / Considerations 34 | - Comprehensive review process needs to be in place, to ensure that any content you put out is correct, ethical and able to be shared publicly 35 | - Time constraints - This will take a bit of time to get setup and going 36 | 37 | ### Case Studies 38 | - [GCHQ](https://github.com/gchq) - They've made a number of their internal tools open source (like the famous [CyberChef](https://github.com/gchq/CyberChef)), now the majority of maintenance is done by the community 39 | - [ElseWhen](https://github.com/elsewhencode/) - A small digital consultancy, which published [project-guidelines](https://github.com/elsewhencode/project-guidelines) helping them get a reputation for good coding standards 40 | - [Novu](https://novu.co/) - They [write great posts](https://dev.to/novu) on dev.to, to share knowledge 41 | - [React](https://github.com/facebook/react) - Started by Facebook, React.JS has now seen over 1000 community contributors, helping with bug fixes, docs and feature development 42 | - RedHat - A multinational company who open source the majority of their offerings, were valued at $34b (by IBM, as of 2019) 43 | 44 | ### Methods 45 | - A GitHub organisation where employees can collate and share public components, utils and knowledge 46 | - By sponsoring existing projects, which are either up and coming, or that you rely upon to do our job 47 | - By contributing to existing projects, when the opportunity to do so arises 48 | - Writing blog posts on a developer-focused site, like Dev.to 49 | 50 | 51 | 52 | 60 | -------------------------------------------------------------------------------- /guides/submit-your-first-pr-cli.md: -------------------------------------------------------------------------------- 1 | # Submit your first PR (Terminal) 2 | 3 | > This page is a work in progress. PRs welcome!
4 | > TODO: I'm going to make instructions clearer, and add screenshots 5 | 6 | 7 | ### 1. Fork the Repository 8 | 9 | - Start by visiting the GitHub page of the repository you wish to contribute to. 10 | - In the top-right corner of the page, click the "Fork" button. This will create a copy of the repository under your GitHub account. 11 | 12 | ### 2. Clone Your Forked Repository 13 | 14 | - On your forked repository's main page, click the green "Code" button. Copy the URL provided. 15 | - Open your terminal or command prompt and navigate to the directory where you want to clone the repository. 16 | Enter: 17 | 18 | ```bash 19 | git clone [URL you copied] 20 | ``` 21 | 22 | This will create a local copy of your forked repository on your machine. 23 | 24 | 25 | ### 3. Navigate to the Repository's Directory 26 | 27 | Enter: 28 | 29 | ```bash 30 | cd [repository-name] 31 | ``` 32 | 33 | ### 4. Set Upstream Remote 34 | 35 | To keep track of the original repository (often called the "upstream"), enter: 36 | 37 | ```bash 38 | git remote add upstream [original repository's URL] 39 | ``` 40 | 41 | ### 5. Create a New Branch 42 | 43 | Always make changes in a new branch instead of directly on main or master. To create and switch to a new branch, enter: 44 | 45 | ```bash 46 | git checkout -b [branch-name] 47 | ``` 48 | 49 | Choose a descriptive branch name related to the changes you're planning to make. 50 | 51 | ### 6. Make Your Changes 52 | 53 | Edit, add, or remove files as needed using your preferred text editor or IDE. 54 | 55 | ### 7. Stage and Commit Changes 56 | 57 | Stage your changes with: 58 | 59 | ```bash 60 | git add . 61 | ``` 62 | 63 | Commit your changes with a descriptive message: 64 | 65 | ```bash 66 | git commit -m "Brief description of changes made" 67 | ``` 68 | 69 | ### 8. Push Changes to Your Fork 70 | 71 | Push your changes to your forked repository on GitHub: 72 | 73 | ```bash 74 | git push origin [branch-name] 75 | ``` 76 | 77 | ### 9. Open a Pull Request (PR) 78 | 79 | - Go back to your forked repository on GitHub. 80 | - Click the "New pull request" button (often GitHub will also present a quick link to create a PR from your recently pushed branch). 81 | - Ensure the base repository is the original repository you want to contribute to, and the head repository is your fork. Also, make sure the branch shown for your fork is the one you just pushed. 82 | - Fill in the PR title and description, detailing your changes and the reason for them. 83 | - Click "Create pull request". 84 | 85 | ### 10. Await Feedback 86 | 87 | - The maintainers of the original repository will review your PR. 88 | - They might request some changes. If they do, repeat steps 6-8, and the PR will automatically update with your new changes. 89 | - Engage in any discussions, answer questions, and make necessary changes as needed. 90 | 91 | ### 11. Keep Your Fork Synced 92 | 93 | Before starting new work, it's a good practice to fetch and merge changes from the upstream (original) repository: 94 | 95 | ```bash 96 | git checkout main 97 | git fetch upstream 98 | git merge upstream/main 99 | git push origin main 100 | ``` 101 | 102 | ### 12. Celebrate! 103 | 104 | Once your PR is merged, you've made a successful contribution! 105 | -------------------------------------------------------------------------------- /lib/insert_resource_list.py: -------------------------------------------------------------------------------- 1 | """ 2 | Reads list of resources from the resources.yml 3 | Then inserts a link to each into the README.md 4 | """ 5 | 6 | import os 7 | import yaml 8 | import logging 9 | from urllib.parse import urlparse 10 | 11 | # Configure Logging 12 | LOG_LEVEL = os.environ.get("LOG_LEVEL", "INFO").upper() 13 | logging.basicConfig(level=LOG_LEVEL) 14 | logger = logging.getLogger(__name__) 15 | 16 | # Determine the project root based on the script's location 17 | project_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) 18 | resources_file_path = os.path.join(project_root, 'resources.yml') 19 | guides_directory = os.path.join(project_root, 'guides') 20 | readme_path = os.path.join(project_root, '.github/README.md') 21 | icon_size=20 22 | 23 | logger.info("Reading the resources.yml file...") 24 | # Read the resources.yml 25 | with open(resources_file_path, 'r') as file: 26 | data = yaml.safe_load(file) 27 | 28 | # Check which guide files exist and prepare their markdown links 29 | guide_links = [] 30 | 31 | for guide in data.get("guides", []): 32 | guide_file_path = os.path.join(guides_directory, f"{guide['file']}.md") 33 | if os.path.exists(guide_file_path): 34 | iconParams = f"?height={icon_size}&color=%23{guide.get('color', '00BBF9')}" 35 | icon = f'
\n"
81 | "
\n"
85 | "\n```mermaid\n"
86 | )
87 |
88 | after = "\n```\n"
89 |
90 | new_content = (
91 | readme_content[:start_idx] +
92 | before +
93 | mermaid_content +
94 | after +
95 | readme_content[end_idx:]
96 | )
97 |
98 | with open(readme_path, "w") as f:
99 | f.write(new_content)
100 |
101 | logger.info("Mermaid content successfully inserted into readme")
102 |
103 | except Exception as e:
104 | logger.error(f"Error inserting mermaid content: {e}")
105 | raise
106 |
107 |
108 | if __name__ == "__main__":
109 | try:
110 | logger.info("Starting the process...")
111 |
112 | with open(mermaid_file, 'r') as f:
113 | mermaid_content = f.read()
114 |
115 | insert_mermaid_into_readme(mermaid_content)
116 | logger.info("All Done!")
117 |
118 | except Exception as e:
119 | logger.error(f"An error occurred: {e}")
120 |
--------------------------------------------------------------------------------
/web/src/pages/guides/submit-your-first-pr-cli.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: ../../layouts/MarkdownLayout.astro
3 | title: Submit your first PR (CLI)
4 | description: Learn how to submit your first code change to a project.
5 | author: None
6 | icon: 'ion:git-branch'
7 | tags: 'None'
8 | index: '3'
9 | created: None
10 | updated: 2023-10-08
11 | ---
12 |
13 |
17 |
18 | # Submit your first PR (Terminal)
19 |
20 | > This page is a work in progress. PRs welcome!🦯 Click here if you cannot see the chart
\n\n" 82 | f"This diagram is written using Mermaid- [view the chart source here]({edit_link})\n\n" 83 | f"[]({view_link})\n" 84 | "21 | > TODO: I'm going to make instructions clearer, and add screenshots 22 | 23 | 24 | ### 1. Fork the Repository 25 | 26 | - Start by visiting the GitHub page of the repository you wish to contribute to. 27 | - In the top-right corner of the page, click the "Fork" button. This will create a copy of the repository under your GitHub account. 28 | 29 | ### 2. Clone Your Forked Repository 30 | 31 | - On your forked repository's main page, click the green "Code" button. Copy the URL provided. 32 | - Open your terminal or command prompt and navigate to the directory where you want to clone the repository. 33 | Enter: 34 | 35 | ```bash 36 | git clone [URL you copied] 37 | ``` 38 | 39 | This will create a local copy of your forked repository on your machine. 40 | 41 | 42 | ### 3. Navigate to the Repository's Directory 43 | 44 | Enter: 45 | 46 | ```bash 47 | cd [repository-name] 48 | ``` 49 | 50 | ### 4. Set Upstream Remote 51 | 52 | To keep track of the original repository (often called the "upstream"), enter: 53 | 54 | ```bash 55 | git remote add upstream [original repository's URL] 56 | ``` 57 | 58 | ### 5. Create a New Branch 59 | 60 | Always make changes in a new branch instead of directly on main or master. To create and switch to a new branch, enter: 61 | 62 | ```bash 63 | git checkout -b [branch-name] 64 | ``` 65 | 66 | Choose a descriptive branch name related to the changes you're planning to make. 67 | 68 | ### 6. Make Your Changes 69 | 70 | Edit, add, or remove files as needed using your preferred text editor or IDE. 71 | 72 | ### 7. Stage and Commit Changes 73 | 74 | Stage your changes with: 75 | 76 | ```bash 77 | git add . 78 | ``` 79 | 80 | Commit your changes with a descriptive message: 81 | 82 | ```bash 83 | git commit -m "Brief description of changes made" 84 | ``` 85 | 86 | ### 8. Push Changes to Your Fork 87 | 88 | Push your changes to your forked repository on GitHub: 89 | 90 | ```bash 91 | git push origin [branch-name] 92 | ``` 93 | 94 | ### 9. Open a Pull Request (PR) 95 | 96 | - Go back to your forked repository on GitHub. 97 | - Click the "New pull request" button (often GitHub will also present a quick link to create a PR from your recently pushed branch). 98 | - Ensure the base repository is the original repository you want to contribute to, and the head repository is your fork. Also, make sure the branch shown for your fork is the one you just pushed. 99 | - Fill in the PR title and description, detailing your changes and the reason for them. 100 | - Click "Create pull request". 101 | 102 | ### 10. Await Feedback 103 | 104 | - The maintainers of the original repository will review your PR. 105 | - They might request some changes. If they do, repeat steps 6-8, and the PR will automatically update with your new changes. 106 | - Engage in any discussions, answer questions, and make necessary changes as needed. 107 | 108 | ### 11. Keep Your Fork Synced 109 | 110 | Before starting new work, it's a good practice to fetch and merge changes from the upstream (original) repository: 111 | 112 | ```bash 113 | git checkout main 114 | git fetch upstream 115 | git merge upstream/main 116 | git push origin main 117 | ``` 118 | 119 | ### 12. Celebrate! 120 | 121 | Once your PR is merged, you've made a successful contribution! 122 | 123 | 124 | 132 | -------------------------------------------------------------------------------- /lib/copy_resources_to_site.py: -------------------------------------------------------------------------------- 1 | """ 2 | Reads the list of resources from the ./resources.yml 3 | For each file, metadata will be inserted as a header 4 | Then copies it over to the website's pages directory 5 | """ 6 | 7 | import os 8 | import yaml 9 | import logging 10 | from pathlib import Path 11 | from datetime import datetime 12 | 13 | 14 | # Configure Logging 15 | LOG_LEVEL = os.environ.get("LOG_LEVEL", "INFO").upper() 16 | logging.basicConfig(level=LOG_LEVEL) 17 | logger = logging.getLogger(__name__) 18 | 19 | 20 | def read_file(file_path: str, mode: str = "r") -> str: 21 | try: 22 | with open(file_path, mode) as file: 23 | logger.info(f"Reading file: {file_path}") 24 | return yaml.safe_load(file) 25 | except FileNotFoundError: 26 | logger.error(f"Error: File {file_path} not found.") 27 | exit(1) 28 | 29 | 30 | def write_file(file_path: str, content: str, mode: str = "w") -> None: 31 | with open(file_path, mode) as f: 32 | logging.info(f"Writing to file: {file_path}") 33 | f.write(content) 34 | 35 | 36 | def main(): 37 | # Get the project root, from location of this script 38 | project_root = Path(__file__).parent.parent 39 | # The location of the YAML file to read resource list from 40 | resources_file_path = project_root / "resources.yml" 41 | # The location of the source guide files 42 | guides_directory = project_root / "guides" 43 | # The location of the destination for the guide files 44 | destination_directory = project_root / "web/src/pages/guides" 45 | 46 | data = read_file(resources_file_path) 47 | 48 | for guide in data["guides"]: 49 | source_file_path = guides_directory / f"{guide['file']}.md" 50 | 51 | if source_file_path.exists(): 52 | destination_file_path = destination_directory / f"{guide['file']}.md" 53 | 54 | header = ( 55 | f"---\n" 56 | f"layout: ../../layouts/MarkdownLayout.astro\n" 57 | f"title: {guide.get('title')}\n" 58 | f"description: {guide.get('description')}\n" 59 | f"author: {guide.get('author')}\n" 60 | f"icon: '{guide.get('icon')}'\n" 61 | f"tags: '{guide.get('tags')}'\n" 62 | f"index: '{guide.get('index')}'\n" 63 | f"created: {guide.get('created')}\n" 64 | f"updated: {datetime.now().strftime('%Y-%m-%d')}\n" 65 | f"---\n\n" 66 | 67 | f"\n\n" 69 | ) 70 | 71 | footer = ( 72 | f"\n\n\n" 80 | ) 81 | 82 | content = header + source_file_path.read_text() + footer 83 | write_file(destination_file_path, content) 84 | logging.info(f"Copied {source_file_path} to {destination_file_path}") 85 | else: 86 | logging.warning(f"Skipping {guide['file']} as doc could not be found in {source_file_path}") 87 | 88 | # Copy the contributing guidleines from ./CONTRIBUTING.md to /web/src/pages/contributing.md 89 | contributing_source_path = project_root / ".github/CONTRIBUTING.md" 90 | contributing_destination_path = project_root / "web/src/pages/contributing.md" 91 | content = contributing_source_path.read_text() 92 | contributing_headers = ( 93 | f"---\n" 94 | f"layout: ../layouts/MarkdownLayout.astro\n" 95 | f"title: Contributing Guidelines\n" 96 | f"---\n\n" 97 | f"\n\n" 98 | ) 99 | write_file(contributing_destination_path, contributing_headers + content) 100 | logging.info(f"Copied {contributing_source_path} to {contributing_destination_path}") 101 | 102 | 103 | if __name__ == "__main__": 104 | main() 105 | -------------------------------------------------------------------------------- /web/public/favicon.svg: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /web/src/assets/img/octocat-colored.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /web/src/components/Contributors.astro: -------------------------------------------------------------------------------- 1 | --- 2 | import yaml from 'js-yaml'; 3 | 4 | const GITHUB_TOKEN = process.env.GH_ACCESS_TOKEN; 5 | 6 | const repo = 'lissy93/git-into-open-source'; 7 | 8 | const contributorCommentsUrl = `https://raw.githubusercontent.com/${repo}/main/git-in-here.yml`; 9 | 10 | const placeholderImage = 'https://i.ibb.co/X231Rq8/octo-no-one.png'; 11 | 12 | const fetchGitHubUserInfo = async (username) => { 13 | const headers = GITHUB_TOKEN ? { 'Authorization': `token ${GITHUB_TOKEN}` } : undefined; 14 | const response = await fetch(`https://api.github.com/users/${username}`, { headers }); 15 | if (!response.ok) return null; 16 | const userInfo = await response.json(); 17 | return { 18 | fullName: userInfo.name || username, 19 | avatarUrl: userInfo.avatar_url || placeholderImage, 20 | }; 21 | }; 22 | 23 | const fetchContributorComments = async () => { 24 | const response = await fetch(contributorCommentsUrl); 25 | const textData = await response.text(); 26 | const data = yaml.load(textData); 27 | 28 | if (!data || !data.contributors) return []; 29 | 30 | // Fetch GitHub user info for each contributor 31 | for (const contributor of data.contributors) { 32 | contributor.profile = `https://github.com/${contributor.username}`; 33 | const userInfo = await fetchGitHubUserInfo(contributor.username); 34 | if (userInfo) { 35 | contributor.fullName = userInfo.fullName; 36 | contributor.avatarUrl = userInfo.avatarUrl; 37 | } 38 | } 39 | 40 | return data.contributors.reverse(); 41 | }; 42 | 43 | const fetchStargazers = async (): Promise
84 | Want to be included here?
85 | Just add your name to git-in-here.yml,
86 | then check out the contributing guide to submit a PR.
87 |
-
89 | {contributors && contributors.map((contributor) => (
90 |
-
91 |
92 |
93 | 94 | {contributor.fullName} 95 | 96 | 97 |
98 | {contributor.question}101 |
99 | {contributor.response} 100 |
102 | ))}
103 |
5 | > TODO: I'm going to make instructions clearer, and add screenshots 6 | 7 | This document covers: 8 | - [Creating a GitHub Account](#creating-a-github-account) 9 | - [Installing Git](#installing-git) 10 | - [Setting up SSH keys](#setting-up-ssh-keys) 11 | - [Configuring the gitconfig](#configuring-the-gitconfig) 12 | 13 | 14 | ## Creating a GitHub Account 15 | 16 | --- 17 | 18 | ## Installing Git 19 | 20 | For official installation downloads and docs, see [git-scm.com/downloads](https://git-scm.com/downloads) 21 | 22 | ### Installing Git on Windows 23 | 24 | [Git for Windows](https://gitforwindows.org/) is a complete package of all the basic git tools you'll need, with an easy GUI installer. 25 | 26 | 1. Download the latest executable from [the Git for Windows Releases](https://github.com/git-for-windows/git/releases) 27 | 2. Run the installer (by double clicking on the downloaded .exe file) 28 | 3. Follow the on-screen instructions to install git onto your machine 29 | 4. Restart explorer.exe (so the new git executable can be found) 30 | 5. Run `git --version` to verify that git has been installed correctly 31 | 32 | ### Installing Git on Mac 33 | 34 | The easiest way to install Git on MacOS is via Homebrew. 35 | 36 | 1. If you don't yet have Brew installed, install it with: 37 | `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` 38 | 2. Then install git with 39 | `brew install git` 40 | 3. Finally, verify git has been installed 41 | `git --version` 42 | 43 | ### Installing Git on Linux 44 | 45 | On Linux, the best method for installing git is using your system's native package manager. Be sure to update your repositories first. You may need to run install commands as `sudo` 46 | 47 | - Debian / Ubuntu: `apt install git` 48 | - Fedora: `dnf install git` 49 | - OpenSUSE: `zypper install git` 50 | - Gentoo: `emerge --ask --verbose dev-vcs/git` 51 | - Arch: `pacman -S git` 52 | - NixOS: `nix-env -i git` 53 | - FreeBSD: `pkg install git` 54 | - OpenBSD: `pkg_add git` 55 | - Alpine: `apk add git` 56 | 57 | --- 58 | 59 | ## Setting up SSH keys 60 | 61 | 62 | ### Intro to SSH 63 | 64 | When you push to a repo, or make any changes from your local machine, you've got two options for auth, HTTPS or SSH. With HTTPS you'll be prompted to enter a username + password each time you push, whereas with SSH you are authenticated automatically if once your key is setup. 65 | 66 | #### What is SSH Auth? 67 | SSH (or Secure Shell) authentication is a method used to establish a secure connection between a client and a server using cryptographic key pairs: a public key (which you share) and a private key (kept secret on your machine). 68 | 69 | #### How It Works: 70 | 1. You generate an SSH key pair (a public key and a private key). 71 | 2. You add the public key to GitHub (or another platform). 72 | 3. When connecting to GitHub, it will challenge the client to prove they have the corresponding private key. 73 | 4. Your machine uses its private key to respond correctly, verifying your identity without ever revealing the key itself. 74 | 75 | #### Benefits Over HTTPS Clone: 76 | - **Security**: Keys are typically more complex than passwords, making them harder to crack. 77 | - **Convenience**: Once set up, no need to enter a username/password with each interaction. 78 | - **Access Control**: Key-based authentication allows finer-grained control, like read-only or full access. 79 | 80 | #### Note for New Users: 81 | It's essential to keep your private key secure and never share it. If someone gains access to it, they have access to everything the key provides access to. Also, using a passphrase when generating SSH keys adds an extra layer of security. 82 | 83 | 84 | ### Setting up SSH 85 | 86 | #### Generating an SSH key 87 | 88 | You may already have a key, in which case you can skip this step. If you do, it'll likely be in a directory named `~/.ssh/`, you can check this by running `ls -al ~/.ssh` - if you see output, and a file ending in `.pub` then you've already got a key! 89 | 90 | Otherwise, we'll generate a new key by running: 91 | 92 | ```bash 93 | ssh-keygen -t ed25519 -C "your_email@example.com" 94 | ``` 95 | 96 |
Note for legacy systems
97 | For legacy systems which does not support Ed25519 algorithm, use: 98 | 99 | ```bash 100 | ssh-keygen -t rsa -b 4096 -C "your_email@example.com" 101 | ``` 102 | 103 |22 | > TODO: I'm going to make instructions clearer, and add screenshots 23 | 24 | This document covers: 25 | - [Creating a GitHub Account](#creating-a-github-account) 26 | - [Installing Git](#installing-git) 27 | - [Setting up SSH keys](#setting-up-ssh-keys) 28 | - [Configuring the gitconfig](#configuring-the-gitconfig) 29 | 30 | 31 | ## Creating a GitHub Account 32 | 33 | --- 34 | 35 | ## Installing Git 36 | 37 | For official installation downloads and docs, see [git-scm.com/downloads](https://git-scm.com/downloads) 38 | 39 | ### Installing Git on Windows 40 | 41 | [Git for Windows](https://gitforwindows.org/) is a complete package of all the basic git tools you'll need, with an easy GUI installer. 42 | 43 | 1. Download the latest executable from [the Git for Windows Releases](https://github.com/git-for-windows/git/releases) 44 | 2. Run the installer (by double clicking on the downloaded .exe file) 45 | 3. Follow the on-screen instructions to install git onto your machine 46 | 4. Restart explorer.exe (so the new git executable can be found) 47 | 5. Run `git --version` to verify that git has been installed correctly 48 | 49 | ### Installing Git on Mac 50 | 51 | The easiest way to install Git on MacOS is via Homebrew. 52 | 53 | 1. If you don't yet have Brew installed, install it with: 54 | `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` 55 | 2. Then install git with 56 | `brew install git` 57 | 3. Finally, verify git has been installed 58 | `git --version` 59 | 60 | ### Installing Git on Linux 61 | 62 | On Linux, the best method for installing git is using your system's native package manager. Be sure to update your repositories first. You may need to run install commands as `sudo` 63 | 64 | - Debian / Ubuntu: `apt install git` 65 | - Fedora: `dnf install git` 66 | - OpenSUSE: `zypper install git` 67 | - Gentoo: `emerge --ask --verbose dev-vcs/git` 68 | - Arch: `pacman -S git` 69 | - NixOS: `nix-env -i git` 70 | - FreeBSD: `pkg install git` 71 | - OpenBSD: `pkg_add git` 72 | - Alpine: `apk add git` 73 | 74 | --- 75 | 76 | ## Setting up SSH keys 77 | 78 | 79 | ### Intro to SSH 80 | 81 | When you push to a repo, or make any changes from your local machine, you've got two options for auth, HTTPS or SSH. With HTTPS you'll be prompted to enter a username + password each time you push, whereas with SSH you are authenticated automatically if once your key is setup. 82 | 83 | #### What is SSH Auth? 84 | SSH (or Secure Shell) authentication is a method used to establish a secure connection between a client and a server using cryptographic key pairs: a public key (which you share) and a private key (kept secret on your machine). 85 | 86 | #### How It Works: 87 | 1. You generate an SSH key pair (a public key and a private key). 88 | 2. You add the public key to GitHub (or another platform). 89 | 3. When connecting to GitHub, it will challenge the client to prove they have the corresponding private key. 90 | 4. Your machine uses its private key to respond correctly, verifying your identity without ever revealing the key itself. 91 | 92 | #### Benefits Over HTTPS Clone: 93 | - **Security**: Keys are typically more complex than passwords, making them harder to crack. 94 | - **Convenience**: Once set up, no need to enter a username/password with each interaction. 95 | - **Access Control**: Key-based authentication allows finer-grained control, like read-only or full access. 96 | 97 | #### Note for New Users: 98 | It's essential to keep your private key secure and never share it. If someone gains access to it, they have access to everything the key provides access to. Also, using a passphrase when generating SSH keys adds an extra layer of security. 99 | 100 | 101 | ### Setting up SSH 102 | 103 | #### Generating an SSH key 104 | 105 | You may already have a key, in which case you can skip this step. If you do, it'll likely be in a directory named `~/.ssh/`, you can check this by running `ls -al ~/.ssh` - if you see output, and a file ending in `.pub` then you've already got a key! 106 | 107 | Otherwise, we'll generate a new key by running: 108 | 109 | ```bash 110 | ssh-keygen -t ed25519 -C "your_email@example.com" 111 | ``` 112 | 113 |
Note for legacy systems
114 | For legacy systems which does not support Ed25519 algorithm, use: 115 | 116 | ```bash 117 | ssh-keygen -t rsa -b 4096 -C "your_email@example.com" 118 | ``` 119 | 120 |" 170 | f"
{response}\n" 172 | ) 173 | return md_content 174 | 175 | 176 | 177 | """ The main entrypoint of the script """ 178 | if __name__ == "__main__": 179 | # Fetch list of stargazers (to insert special emoji next to name) 180 | all_stargazers = fetch_all_stargazers(REPO_OWNER, REPO_NAME, GH_ACCESS_TOKEN) 181 | # Read YAML 182 | yaml_content = yaml.safe_load(read_file(CONTRIBUTORS_FILE_PATH)) 183 | # Read current README 184 | readme_content = read_file(README_PATH) 185 | # Generate content to be inserted 186 | new_md_content = build_markdown_content( 187 | yaml_content["contributors"], all_stargazers 188 | ) 189 | # Locate and replace content in README 190 | start_marker = "" 191 | end_marker = "" 192 | start_index = readme_content.find(start_marker) + len(start_marker) 193 | end_index = readme_content.find(end_marker) 194 | # Create new readme (from old readme + new content) 195 | new_readme_content = ( 196 | readme_content[:start_index] 197 | + "\n" 198 | + new_md_content 199 | + readme_content[end_index:] 200 | ) 201 | # Write readme content back to file 202 | write_file(README_PATH, new_readme_content) 203 | logging.info("All Done!") 204 | 205 | """ 206 | Okay, you've got this far... 207 | As you can tell this is a pretty quickly-put-together and hacky script 208 | And there's definitely plenty of room for improvement! 209 | So if you're up for it, feel free to submit a PR :) 210 | """ 211 | -------------------------------------------------------------------------------- /.github/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | 2 | ## Introduction 3 | 4 | One of the biggest barriers to entry for first-time and newer contributors is the Git and GitHub process. The aim of this repo is to provide an easy and safe space for you to get more comfortable with the contribution process. We welcome PRs from developers of all levels and experiences, and we've tried to make the process as straightforward as possible. 5 | 6 | | ⚠️ Important: Before submitting your pull request, please ensure you're following [these Guidelines](#guidelines)! | 7 | |--| 8 | 9 | --- 10 | 11 | ## How 12 | 13 | You've got two options: The easiest, and sometimes best for just small changes is to use the GitHub UI, or Codespaces - this is explained in [this step-by-step tutorial](https://github.com/Lissy93/git-into-open-source/blob/main/guides/submit-your-first-pr-ui.md). 14 | In the longer term, and especially once you're working on larger changes, you'll want to have Git installed on your system, and make changes locally, again instructions for which are [outlined here](https://github.com/Lissy93/git-into-open-source/blob/main/guides/submit-your-first-pr-cli.md). 15 | 16 | Prerequisites: You will need a GitHub account. If you're planning on making changes via the terminal, you'll also need Git installed, and an SSH key setup on your local system. 17 | For a step-by-step guide, see [setting up Git, GitHub, SSH](https://github.com/Lissy93/git-into-open-source/blob/main/guides/local-git-setup.md) 18 | 19 | --- 20 | 21 | ## Areas for Contribution 22 | 23 | Not sure what to add or work on? Here's 10 ideas to get you started! 24 | 25 | ### Add your Name! 26 | 27 | This is probably the easiest place to start for first-time contributors. On the readme, there's a list of names and comments from developers, and you can add yours in there too! 28 | 29 | It's important to note that you don't put this in the readme directly, but rather edit the [`git-in-here.yml`](https://github.com/Lissy93/git-into-open-source/blob/main/git-in-here.yml) file instead (there's a template at the top), this is then fetches some additional info from the GitHub API (like your name, picture and stargazer status) and inserts it into the readme using [this workflow](https://github.com/Lissy93/git-into-open-source/blob/main/.github/workflows/insert-comments.yml) running on GitHub Actions. 30 | 31 | ### Guides 32 | 33 | I'm working on putting together a series of guides, aimed at helping new developers get up to speed with Git, and get into Open Source. 34 | 35 | These can be found in the [`/guides`](https://github.com/Lissy93/git-into-open-source/tree/main/guides) directory, and any contributions would be much appreciated! If you're adding a new guide, it also needs to be listed in the [`resources.yml`](https://github.com/Lissy93/git-into-open-source/blob/main/resources.yml) file, for it to be shown on the website and in the readme. 36 | 37 | ### Resources 38 | 39 | The readme and website also list to some helpful external resources, as there's no point reinventing the wheel when there are already some excellent guides and tools out there. 40 | 41 | If you know of any sites that are not already listed, which you think could be helpful, you can add these into the [`resources.yml`](https://github.com/Lissy93/git-into-open-source/blob/main/resources.yml) file (under the `resources` section), and they'll be automatically inserted into the readme (using [this workflow](https://github.com/Lissy93/git-into-open-source/blob/main/.github/workflows/insert-resources.yml)). 42 | 43 | Keep in mind - I would ideally like to keep the resources list short, with only the best tools and websites listed, so if you're adding something ensure it meets this criteria, and provide justification. 44 | 45 | ### Website 46 | 47 | We've also got a simple static site, that makes it easier to read some of the guides; it's hosted on GitHub Pages, at [lissy93.github.io/git-into-open-source](https://lissy93.github.io/git-into-open-source/) 48 | 49 | It's built using [Astro](https://astro.build/), so is very easy to get up to speed with quickly. The source, as well as setup docs can be found in the [`web/`](https://github.com/Lissy93/git-into-open-source/tree/main/web) directory. 50 | 51 | ### Scripting 52 | 53 | The repo is held together with a set of pretty simple Python scripts that insert the user-contributed content in the readme, and make it available via the website. 54 | 55 | These can be found in the [`/lib`](https://github.com/Lissy93/git-into-open-source/tree/main/lib) directory. 56 | 57 | If you're a Python developer, you'll see that there's plenty of room for improvement here! Whether it's refactoring, writing tests, fixing a bug, adding a feature or anything else - PRs here are very much welcome! 58 | 59 | ### Docs 60 | 61 | Have you noticed anything not right in the readme or any of the other docs here? Whether it's correcting spelling / grammar, improving instructions or fixing formatting - pull requests are always appreciated! 62 | 63 | ### Translations 64 | 65 | // TODO: I need to first add the architecture for this! 66 | 67 | ### Something Else? 68 | 69 | I'm up for reviewing pull requests for other areas of this repository, not listed above. If you're unsure if your intended contribution would be a good fit or not, feel free to open an issue first, and we can chat about it :) 70 | 71 | ### Not a coder? 72 | 73 | There's plenty of other ways you can support open source projects! 74 | 75 | - Open an issue to report a bug 76 | - Write a tutorial or blog post 77 | - Leaving constructive feedback 78 | - Reviewing open pull requests 79 | - Contributing to docs 80 | - Adding international translations 81 | - Helping with testing 82 | - Assisting with UI, UX or asset design 83 | - Sponsoring the project or author 84 | - Sharing the project within your network 85 | 86 | ### Still nothing? 87 | 88 | There's plenty of other repositories on GitHub looking for contributors! Whatever your skill set or level, there will surly be the perfect project for your first few open source contributions. Take a look at this guide: [Finding Projects to Contribute to](https://github.com/Lissy93/git-into-open-source/blob/main/guides/finding-projects-to-contribute-to.md) 89 | 90 | --- 91 | 92 | ## Guidelines 93 | 94 | > ‼️ Please familiarise yourself with this checklist **before** submitting your pull request.
95 | > ❌ PRs which do not follow these guidelines, or that are low-effort will **not be merged**.
96 | > ⭕ These requirements are in place in order to keep the content in this repo high quality :) 97 | 98 | When submitting a pull request, you must: 99 | - Complete the PR template appropriately 100 | - Agree to follow the Code of Conduct 101 | - Not submit low-effort or AI-generated content 102 | 103 | When adding your name and response to [`git-in-here.yml`](https://github.com/Lissy93/git-into-open-source/blob/main/git-in-here.yml), 104 | you must ensure that: 105 | - Your addition must be appended to the end of the file 106 | - The file must end in a single blank line 107 | - The username must match YOUR GitHub username 108 | - The question must exist in the list 109 | - The response should be between 64 and 512 characters 110 | - The response should be wrapped onto the next line if it's over 100 chars 111 | - The response must not be spammy, low effort or AI-generated (important!) 112 | - The response must be in English, with correct spelling and grammar 113 | 114 | Top tips for adding a great response: 115 | - **Be imaginative!** Ensure your response is something that will engage, educate, or delight those who read it in the future  116 | - Great advice, insightful thoughts, jokes and fun facts are all awesome 117 | - **Markdown is supported!** So you can include links and basic formatting 118 | - Feel free to link to your projects, website or helpful (SFW) resources 119 | - Hyperlinks (`[text to display](https://example.com)`), new lines (`
`) as well as `**bold**` and `_italic_` all work 120 | - **Get a gold star by your name!** Drop a star on this repo, and you'll automatically get a star next to your response 121 | 122 | When adding a resource to [`resources.yml`](https://github.com/Lissy93/git-into-open-source/blob/main/resources.yml), 123 | you must: 124 | - Not submit blog posts or articles, unless they provide considerable value to the reader 125 | - Not submit anything which is duplicate content, or very similar to an existing resource 126 | - Disclose any association you may have to that website 127 | - Provide a short sentence of justification in your PR, explaining why it should be included 128 | 129 | When submitting additions or changes to the guides in [`guides/`](https://github.com/Lissy93/git-into-open-source/tree/main/guides), 130 | you must: 131 | - Ensure all new information is, to the best of your knowledge accurate and correct 132 | - Spell and grammar check your new additions, and ensure that any included links are functional 133 | - Not provide links to content you own, manage or are affiliated with, without disclosing your association when submitting the pull request 134 | - If you're adding a new guide, don't forget to also list it in the resources file, so it can be indexed 135 | 136 | When submitting changes to the website in [`web/`](https://github.com/Lissy93/git-into-open-source/tree/main/web), 137 | you must: 138 | - Ensure the application is still fully deployable 139 | - Ensure there are no regressions / no new bugs introduced 140 | - Ensure all lint checks, tests and build scripts still pass 141 | 142 | When submitting changes to the website in [`lib/`](https://github.com/Lissy93/git-into-open-source/tree/main/lib), 143 | you must: 144 | - Ensure that all scripts still run as expected 145 | - Ensure there are no regressions / no new bugs introduced 146 | - Ensure all lint checks, tests and build scripts still pass 147 | 148 | There's a few no-go zones, where changes will be overridden by the dynamically inserted content. Therefore: 149 | - When editing markdown, do not manually submit any content between the `` and `` tags - this is auto-generated, and so will be overridden! 150 | - Don't edit the markdown within the `web/` directory, as this is generated using the content from `/guides`, and metadata from `resources.yml` 151 | - Only submit pull requests to the repo on GitHub (lissy93/git-into-open-source), as our Codeberg mirror is one-way, so changes will be overridden 152 | -------------------------------------------------------------------------------- /web/src/pages/contributing.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: ../layouts/MarkdownLayout.astro 3 | title: Contributing Guidelines 4 | --- 5 | 6 | 7 | 8 | 9 | ## Introduction 10 | 11 | One of the biggest barriers to entry for first-time and newer contributors is the Git and GitHub process. The aim of this repo is to provide an easy and safe space for you to get more comfortable with the contribution process. We welcome PRs from developers of all levels and experiences, and we've tried to make the process as straightforward as possible. 12 | 13 | | ⚠️ Important: Before submitting your pull request, please ensure you're following [these Guidelines](#guidelines)! | 14 | |--| 15 | 16 | --- 17 | 18 | ## How 19 | 20 | You've got two options: The easiest, and sometimes best for just small changes is to use the GitHub UI, or Codespaces - this is explained in [this step-by-step tutorial](https://github.com/Lissy93/git-into-open-source/blob/main/guides/submit-your-first-pr-ui.md). 21 | In the longer term, and especially once you're working on larger changes, you'll want to have Git installed on your system, and make changes locally, again instructions for which are [outlined here](https://github.com/Lissy93/git-into-open-source/blob/main/guides/submit-your-first-pr-cli.md). 22 | 23 | Prerequisites: You will need a GitHub account. If you're planning on making changes via the terminal, you'll also need Git installed, and an SSH key setup on your local system. 24 | For a step-by-step guide, see [setting up Git, GitHub, SSH](https://github.com/Lissy93/git-into-open-source/blob/main/guides/local-git-setup.md) 25 | 26 | --- 27 | 28 | ## Areas for Contribution 29 | 30 | Not sure what to add or work on? Here's 10 ideas to get you started! 31 | 32 | ### Add your Name! 33 | 34 | This is probably the easiest place to start for first-time contributors. On the readme, there's a list of names and comments from developers, and you can add yours in there too! 35 | 36 | It's important to note that you don't put this in the readme directly, but rather edit the [`git-in-here.yml`](https://github.com/Lissy93/git-into-open-source/blob/main/git-in-here.yml) file instead (there's a template at the top), this is then fetches some additional info from the GitHub API (like your name, picture and stargazer status) and inserts it into the readme using [this workflow](https://github.com/Lissy93/git-into-open-source/blob/main/.github/workflows/insert-comments.yml) running on GitHub Actions. 37 | 38 | ### Guides 39 | 40 | I'm working on putting together a series of guides, aimed at helping new developers get up to speed with Git, and get into Open Source. 41 | 42 | These can be found in the [`/guides`](https://github.com/Lissy93/git-into-open-source/tree/main/guides) directory, and any contributions would be much appreciated! If you're adding a new guide, it also needs to be listed in the [`resources.yml`](https://github.com/Lissy93/git-into-open-source/blob/main/resources.yml) file, for it to be shown on the website and in the readme. 43 | 44 | ### Resources 45 | 46 | The readme and website also list to some helpful external resources, as there's no point reinventing the wheel when there are already some excellent guides and tools out there. 47 | 48 | If you know of any sites that are not already listed, which you think could be helpful, you can add these into the [`resources.yml`](https://github.com/Lissy93/git-into-open-source/blob/main/resources.yml) file (under the `resources` section), and they'll be automatically inserted into the readme (using [this workflow](https://github.com/Lissy93/git-into-open-source/blob/main/.github/workflows/insert-resources.yml)). 49 | 50 | Keep in mind - I would ideally like to keep the resources list short, with only the best tools and websites listed, so if you're adding something ensure it meets this criteria, and provide justification. 51 | 52 | ### Website 53 | 54 | We've also got a simple static site, that makes it easier to read some of the guides; it's hosted on GitHub Pages, at [lissy93.github.io/git-into-open-source](https://lissy93.github.io/git-into-open-source/) 55 | 56 | It's built using [Astro](https://astro.build/), so is very easy to get up to speed with quickly. The source, as well as setup docs can be found in the [`web/`](https://github.com/Lissy93/git-into-open-source/tree/main/web) directory. 57 | 58 | ### Scripting 59 | 60 | The repo is held together with a set of pretty simple Python scripts that insert the user-contributed content in the readme, and make it available via the website. 61 | 62 | These can be found in the [`/lib`](https://github.com/Lissy93/git-into-open-source/tree/main/lib) directory. 63 | 64 | If you're a Python developer, you'll see that there's plenty of room for improvement here! Whether it's refactoring, writing tests, fixing a bug, adding a feature or anything else - PRs here are very much welcome! 65 | 66 | ### Docs 67 | 68 | Have you noticed anything not right in the readme or any of the other docs here? Whether it's correcting spelling / grammar, improving instructions or fixing formatting - pull requests are always appreciated! 69 | 70 | ### Translations 71 | 72 | // TODO: I need to first add the architecture for this! 73 | 74 | ### Something Else? 75 | 76 | I'm up for reviewing pull requests for other areas of this repository, not listed above. If you're unsure if your intended contribution would be a good fit or not, feel free to open an issue first, and we can chat about it :) 77 | 78 | ### Not a coder? 79 | 80 | There's plenty of other ways you can support open source projects! 81 | 82 | - Open an issue to report a bug 83 | - Write a tutorial or blog post 84 | - Leaving constructive feedback 85 | - Reviewing open pull requests 86 | - Contributing to docs 87 | - Adding international translations 88 | - Helping with testing 89 | - Assisting with UI, UX or asset design 90 | - Sponsoring the project or author 91 | - Sharing the project within your network 92 | 93 | ### Still nothing? 94 | 95 | There's plenty of other repositories on GitHub looking for contributors! Whatever your skill set or level, there will surly be the perfect project for your first few open source contributions. Take a look at this guide: [Finding Projects to Contribute to](https://github.com/Lissy93/git-into-open-source/blob/main/guides/finding-projects-to-contribute-to.md) 96 | 97 | --- 98 | 99 | ## Guidelines 100 | 101 | > ‼️ Please familiarise yourself with this checklist **before** submitting your pull request.
102 | > ❌ PRs which do not follow these guidelines, or that are low-effort will **not be merged**.
103 | > ⭕ These requirements are in place in order to keep the content in this repo high quality :) 104 | 105 | When submitting a pull request, you must: 106 | - Complete the PR template appropriately 107 | - Agree to follow the Code of Conduct 108 | - Not submit low-effort or AI-generated content 109 | 110 | When adding your name and response to [`git-in-here.yml`](https://github.com/Lissy93/git-into-open-source/blob/main/git-in-here.yml), 111 | you must ensure that: 112 | - Your addition must be appended to the end of the file 113 | - The file must end in a single blank line 114 | - The username must match YOUR GitHub username 115 | - The question must exist in the list 116 | - The response should be between 64 and 512 characters 117 | - The response should be wrapped onto the next line if it's over 100 chars 118 | - The response must not be spammy, low effort or AI-generated (important!) 119 | - The response must be in English, with correct spelling and grammar 120 | 121 | Top tips for adding a great response: 122 | - **Be imaginative!** Ensure your response is something that will engage, educate, or delight those who read it in the future  123 | - Great advice, insightful thoughts, jokes and fun facts are all awesome 124 | - **Markdown is supported!** So you can include links and basic formatting 125 | - Feel free to link to your projects, website or helpful (SFW) resources 126 | - Hyperlinks (`[text to display](https://example.com)`), new lines (`
`) as well as `**bold**` and `_italic_` all work 127 | - **Get a gold star by your name!** Drop a star on this repo, and you'll automatically get a star next to your response 128 | 129 | When adding a resource to [`resources.yml`](https://github.com/Lissy93/git-into-open-source/blob/main/resources.yml), 130 | you must: 131 | - Not submit blog posts or articles, unless they provide considerable value to the reader 132 | - Not submit anything which is duplicate content, or very similar to an existing resource 133 | - Disclose any association you may have to that website 134 | - Provide a short sentence of justification in your PR, explaining why it should be included 135 | 136 | When submitting additions or changes to the guides in [`guides/`](https://github.com/Lissy93/git-into-open-source/tree/main/guides), 137 | you must: 138 | - Ensure all new information is, to the best of your knowledge accurate and correct 139 | - Spell and grammar check your new additions, and ensure that any included links are functional 140 | - Not provide links to content you own, manage or are affiliated with, without disclosing your association when submitting the pull request 141 | - If you're adding a new guide, don't forget to also list it in the resources file, so it can be indexed 142 | 143 | When submitting changes to the website in [`web/`](https://github.com/Lissy93/git-into-open-source/tree/main/web), 144 | you must: 145 | - Ensure the application is still fully deployable 146 | - Ensure there are no regressions / no new bugs introduced 147 | - Ensure all lint checks, tests and build scripts still pass 148 | 149 | When submitting changes to the website in [`lib/`](https://github.com/Lissy93/git-into-open-source/tree/main/lib), 150 | you must: 151 | - Ensure that all scripts still run as expected 152 | - Ensure there are no regressions / no new bugs introduced 153 | - Ensure all lint checks, tests and build scripts still pass 154 | 155 | There's a few no-go zones, where changes will be overridden by the dynamically inserted content. Therefore: 156 | - When editing markdown, do not manually submit any content between the `` and `` tags - this is auto-generated, and so will be overridden! 157 | - Don't edit the markdown within the `web/` directory, as this is generated using the content from `/guides`, and metadata from `resources.yml` 158 | - Only submit pull requests to the repo on GitHub (lissy93/git-into-open-source), as our Codeberg mirror is one-way, so changes will be overridden 159 | --------------------------------------------------------------------------------