diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 11f4563..deeaab5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -52,20 +52,42 @@ Before contributing, make sure you have: ### Documentation Structure -Our documentation is organized as follows: +Our documentation is organized in a progressive learning path. Follow the structure below when adding new content: ``` docs/ -├── getting-started.md # Getting started guide -├── js/ # JavaScript documentation -│ ├── basics.md # JavaScript basics -│ └── advanced.md # Advanced JavaScript -├── ts/ # TypeScript documentation -│ ├── intro.md # TypeScript introduction -│ └── tips.md # TypeScript tips -└── react-native/ # React Native documentation - ├── setup.md # React Native setup - └── components.md # React Native components +├── getting-started.md # Getting started guide +├── intro.md # Project overview +│ +├── Javascript/ # JavaScript documentation +│ ├── Beginner/ # Foundation concepts +│ │ ├── introduction-to-javascript.md # What is JavaScript? +│ │ ├── variables.md # Variables and data types +│ │ ├── arrays.md # Working with arrays +│ │ ├── functions.md # Functions and scope +│ │ ├── objects.md # Objects and methods +│ │ └── projects.md # Beginner projects +│ │ +│ └── Intermediate/ # Advanced concepts +│ ├── advanced-functions.md # Advanced function patterns +│ ├── dom-manipulation.md # DOM interaction +│ ├── es6-features.md # Modern JavaScript features +│ ├── async-javascript/ # Asynchronous programming +│ │ ├── callbacks.md # Callback functions +│ │ ├── promises.md # Promise patterns +│ │ ├── async-await.md # Async/await syntax +│ │ └── asynchronous-operations.md # Complex async operations +│ ├── json-apis.md # Working with APIs +│ ├── error-handling.md # Error handling patterns +│ └── final-projects.md # Intermediate projects +│ +├── Typescript/ # TypeScript documentation +│ ├── intro.md # TypeScript introduction +│ └── tips.md # TypeScript best practices +│ +└── react-native/ # React Native documentation + ├── setup.md # Environment setup + └── components.md # Component development ``` ### Writing Guidelines @@ -151,17 +173,130 @@ Always use `map()` when you need to transform array elements. It's more function - Screenshots if you've made visual changes - References to any related issues +### Branch Naming Conventions + +To help with code reviews and project organization, please follow these branching guidelines: + +#### Branch Naming Format + +Use the following format for your branch names: + +``` +/ +``` + +#### Branch Types + +| Type | Purpose | Example | +| ---------- | -------------------------- | -------------------------------------- | +| `feat` | New features or content | `feat/add-async-await-tutorial` | +| `fix` | Bug fixes or corrections | `fix/broken-links-javascript-section` | +| `docs` | Documentation improvements | `docs/improve-contributing-guide` | +| `style` | Design/UI improvements | `style/enhance-mobile-navigation` | +| `refactor` | Code/content restructuring | `refactor/reorganize-beginner-content` | +| `test` | Adding or fixing tests | `test/add-code-example-validation` | +| `chore` | Maintenance tasks | `chore/update-dependencies` | + +#### Branch Naming Examples + +✅ **Good Examples:** + +```bash +feat/typescript-generics-tutorial +fix/incorrect-array-examples +docs/update-installation-guide +style/improve-code-block-styling +refactor/split-large-javascript-file +``` + +❌ **Avoid:** + +```bash +my-changes +update +fix-stuff +new-feature +``` + +#### Creating and Working with Branches + +1. **Create a new branch** from main: + + ```bash + git checkout main + git pull upstream main # Sync with latest changes + git checkout -b feat/your-feature-name + ``` + +2. **Make your changes** and commit regularly: + + ```bash + git add . + git commit -m "Add: Clear description of what you added" + ``` + +3. **Push your branch** to your fork: + + ```bash + git push origin feat/your-feature-name + ``` + +4. **Create a Pull Request** with a clear title matching your branch purpose + +### Commit Message Guidelines + +Use clear, descriptive commit messages that follow this format: + +``` +: + +[Optional longer description] +``` + +**Examples:** + +```bash +feat: Add TypeScript interfaces tutorial +fix: Correct array method examples in beginner guide +docs: Update contribution guidelines with branch naming +style: Improve responsive design for mobile devices +``` + +**Types for commits:** + +- `feat:` New features or content +- `fix:` Bug fixes +- `docs:` Documentation changes +- `style:` Formatting, UI changes +- `refactor:` Code restructuring +- `test:` Adding tests +- `chore:` Maintenance + ### Pull Request Checklist Before submitting your pull request, make sure: +- [ ] Your branch name follows our naming conventions - [ ] The documentation builds without errors (`npm run build`) - [ ] All code examples are tested and work correctly - [ ] Links are working and point to the correct pages - [ ] Grammar and spelling are correct - [ ] The content follows our style guidelines +- [ ] Your commits have clear, descriptive messages +- [ ] You've synced with the latest main branch - [ ] You've added yourself to the contributors list (if applicable) +### Review Process + +To help us review your contribution quickly: + +1. **Use descriptive PR titles** that match your branch type +2. **Fill out the PR template** completely +3. **Reference related issues** using `#issue-number` +4. **Add screenshots** for visual changes +5. **Request specific reviewers** if you know who should review +6. **Respond to feedback** promptly and professionally + ## 🐛 Reporting Issues If you find bugs, typos, or have suggestions for improvement: diff --git a/Readme.md b/Readme.md index ef09c7f..044b385 100644 --- a/Readme.md +++ b/Readme.md @@ -33,21 +33,54 @@ Welcome to the **Modern JavaScript Documentation** – a comprehensive learning ## 🗺️ Documentation Structure +Our documentation is organized in a progressive learning path. **Follow the topics in order** for the best learning experience, as each section builds upon concepts from previous ones. + ``` 📁 docs/ -├── 🚀 getting-started.md # Start your journey here -├── 📄 intro.md # Project overview -├── 🟨 js/ # JavaScript Documentation -│ ├── basics.md # Variables, functions, objects -│ └── advanced.md # Async/await, modules, patterns -├── 🔷 ts/ # TypeScript Documentation -│ ├── intro.md # Getting started with TypeScript -│ └── tips.md # Best practices and tips -└── 📱 react-native/ # React Native Documentation - ├── setup.md # Environment setup - └── components.md # Building components +├── 🚀 getting-started.md # Start your journey here +├── 📄 intro.md # Project overview +│ +├── 🟨 Javascript/ # JavaScript Documentation +│ ├── 📚 Beginner/ # Foundation Concepts (Start Here) +│ │ ├── introduction-to-javascript.md # 1. What is JavaScript? +│ │ ├── variables.md # 2. Storing data +│ │ ├── arrays.md # 3. Working with lists +│ │ ├── functions.md # 4. Reusable code blocks +│ │ ├── objects.md # 5. Organizing data +│ │ └── projects.md # 6. Practice projects +│ │ +│ └── 🔥 Intermediate/ # Advanced Concepts (After Beginner) +│ ├── advanced-functions.md # 7. Function mastery +│ ├── dom-manipulation.md # 8. Web page interaction +│ ├── es6-features.md # 9. Modern JavaScript +│ ├── async-javascript/ # 10. Asynchronous Programming +│ │ ├── callbacks.md # 10a. Basic async +│ │ ├── promises.md # 10b. Promise patterns +│ │ ├── async-await.md # 10c. Modern async +│ │ └── asynchronous-operations.md # 10d. Complex operations +│ ├── json-apis.md # 11. Working with APIs +│ ├── error-handling.md # 12. Handling errors +│ └── final-projects.md # 13. Capstone projects +│ +├── 🔷 Typescript/ # TypeScript Documentation (After JS Intermediate) +│ ├── intro.md # Getting started with TypeScript +│ └── tips.md # Best practices and tips +│ +└── 📱 react-native/ # React Native Documentation (After TypeScript) + ├── setup.md # Environment setup + └── components.md # Building components ``` +### 📚 **Learning Path Recommendations** + +> **🎯 Important**: Follow the numbered sequence above for optimal learning progression. Each topic introduces concepts that are essential for understanding subsequent materials. + +**Beginner Path**: `getting-started` → `Javascript/Beginner` (1-6) → Practice projects + +**Intermediate Path**: Complete Beginner → `Javascript/Intermediate` (7-13) → Build real applications + +**Advanced Path**: Complete Intermediate → `Typescript` → `React Native` → Advanced projects + ## 🚀 Quick Start for Contributors ### Prerequisites @@ -55,23 +88,34 @@ Welcome to the **Modern JavaScript Documentation** – a comprehensive learning - **Node.js** (v16 or higher) - **npm** or **yarn** - **Git** for version control +- **GitHub account** for contributing -### Setup Instructions +### 🍴 Fork & Setup Instructions -1. **Clone the repository** +1. **Fork the repository** + + Click the "Fork" button at the top right of the [repository page](https://github.com/sammy6378/reference) to create your own copy. + +2. **Clone your fork** ```bash - git clone https://github.com/sammy6378/reference.git + git clone https://github.com/YOUR_USERNAME/reference.git cd reference ``` -2. **Install dependencies** +3. **Add upstream remote** + + ```bash + git remote add upstream https://github.com/sammy6378/reference.git + ``` + +4. **Install dependencies** ```bash npm install ``` -3. **Start the development server** +5. **Start the development server** ```bash npm start @@ -79,73 +123,177 @@ Welcome to the **Modern JavaScript Documentation** – a comprehensive learning The site will be available at [http://localhost:3000](http://localhost:3000) -4. **Start contributing!** 🎉 +6. **Create a new branch for your changes** + + ```bash + git checkout -b feature/your-feature-name + ``` + +7. **Make your changes and test them locally** + +8. **Commit and push your changes** + + ```bash + git add . + git commit -m "Add: descriptive commit message" + git push origin feature/your-feature-name + ``` + +9. **Create a Pull Request** + + Go to your fork on GitHub and click "New Pull Request". Provide a clear description of your changes. ## 📝 How to Contribute -We welcome contributions from developers of all experience levels! Here's how you can help: +We welcome contributions from developers of all experience levels! Here are the ways you can help: + +### 🔄 **Contribution Workflow** + +1. **Fork** the repository to your GitHub account +2. **Clone** your fork locally +3. **Create a branch** for your specific changes +4. **Make your changes** following our guidelines +5. **Test** your changes locally +6. **Commit** with clear, descriptive messages +7. **Push** to your fork +8. **Submit a Pull Request** with detailed description ### 🐛 **Report Issues** -- Found a typo or error? [Open an issue](https://github.com/sammy6378/reference/issues) -- Suggestions for new content? We'd love to hear them! +- Found a typo, broken link, or error? [Open an issue](https://github.com/sammy6378/reference/issues) +- Use our issue templates for bug reports and feature requests +- Provide as much detail as possible to help us understand the problem -### ✍️ **Improve Documentation** +### ✍️ **Improve Existing Documentation** - Fix typos and improve clarity -- Add missing examples or explanations -- Translate content (coming soon) +- Update outdated examples or explanations +- Add missing code examples +- Improve existing tutorials ### 🆕 **Add New Content** -- Write tutorials for new topics -- Create interactive examples -- Add best practices and tips +Before adding new content: -### 🎨 **Enhance Design** +- Check existing issues to see if it's already planned +- Open a discussion or issue to propose your idea +- Follow our content structure and style guidelines -- Improve the user interface -- Add new components +Types of content we're looking for: + +- New JavaScript concepts and features +- TypeScript tutorials and examples +- React Native components and patterns +- Best practices and coding standards +- Real-world project examples + +### 🎨 **Enhance Design & User Experience** + +- Improve the website's user interface +- Add new Docusaurus components - Optimize for mobile devices +- Enhance accessibility features ### 📋 **Content Guidelines** When contributing content, please follow these guidelines: -1. **Be Beginner-Friendly**: Assume readers are new to the topic -2. **Use Clear Examples**: Include practical, runnable code snippets -3. **Stay Current**: Focus on modern approaches and best practices -4. **Add Context**: Explain not just "how" but "why" -5. **Test Your Code**: Ensure all examples work as expected +1. **Be Beginner-Friendly**: + - Assume readers are new to the topic + - Define technical terms when first used + - Provide context and background information + +2. **Use Clear, Practical Examples**: + - Include runnable code snippets + - Show both correct and incorrect examples when helpful + - Use real-world scenarios + +3. **Stay Current**: + - Focus on modern approaches and best practices + - Use the latest stable versions of tools/frameworks + - Avoid deprecated methods unless explaining migration + +4. **Structure Content Well**: + - Use clear headings and subheadings + - Break up long sections with examples + - Include summary sections + +5. **Test Everything**: + - Ensure all code examples work as expected + - Test on different browsers/devices when relevant + - Verify all links are working ### 📂 **File Structure for New Content** +When creating new documentation files: + ```markdown --- sidebar_position: 1 title: Your Topic Title -description: Brief description of what this covers +description: Brief description for SEO and previews +tags: [javascript, beginner, tutorial] --- # Your Topic Title -Brief introduction explaining what the reader will learn. +Brief introduction explaining what the reader will learn and why it's important. ## Prerequisites + - What knowledge is assumed - Required tools or setup +- Links to prerequisite topics + +## Learning Objectives + +By the end of this tutorial, you will: +- Objective 1 +- Objective 2 +- Objective 3 ## Main Content -Your tutorial content with examples... + +Your tutorial content with practical examples... + +### Code Examples + +```javascript +// Always include comments explaining the code +const example = "Keep examples simple and focused"; +console.log(example); +``` + +## Practice Exercise + +Hands-on exercise for readers to test their understanding. ## Summary -Key takeaways and next steps -## Further Reading -- Links to related topics -- External resources +- Key takeaway 1 +- Key takeaway 2 +- Key takeaway 3 + +## Next Steps + +- What to learn next +- Related topics to explore + +## Additional Resources + +- [Link to official documentation](https://example.com) +- [Related tutorial](./related-topic.md) + ``` +### 🚫 **What NOT to Include** + +- Copyrighted content without permission +- Outdated or deprecated methods (unless explaining migration) +- Personal opinions presented as facts +- Content that doesn't add educational value +- Incomplete or untested code examples + ## 🛠️ Development Commands | Command | Description |