🤝 Contributing to Android-Arsenal-Java

First off, thank you for considering contributing to Android-Arsenal-Java! 🎉 It's people like you that make this learning resource truly valuable for the Android developer community.

📋 Table of Contents

Code of Conduct
How Can I Contribute?
Getting Started
Contribution Workflow
Style Guidelines
Commit Message Guidelines
Pull Request Process
Community

📜 Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [your.email@example.com].

In short:

✅ Be respectful and inclusive
✅ Welcome newcomers warmly
✅ Accept constructive criticism gracefully
❌ No harassment or discrimination
❌ No trolling or insulting comments

🎯 How Can I Contribute?

There are many ways to contribute to this project, and all are valued!

1. 📝 Improve Documentation

What you can do:

Fix typos or grammatical errors
Clarify confusing explanations
Add missing topics or concepts
Improve code comments
Update outdated information
Add diagrams or flowcharts

Examples:

✅ GOOD: "Clarified RecyclerView adapter implementation in Stage 2"
✅ GOOD: "Added diagram explaining Activity lifecycle"
✅ GOOD: "Fixed broken links in Stage 3 README"

2. 💻 Add Code Examples

What you can do:

Create working code snippets
Add commented examples for concepts
Provide alternative implementations
Add error handling examples

Requirements:

Code must compile and run
Include clear comments
Follow Java best practices
Test thoroughly before submitting

Example structure:

/**
 * Demonstrates basic RecyclerView implementation
 * Topics covered: Adapter, ViewHolder, LayoutManager
 * Difficulty: Beginner
 */
public class SimpleAdapter extends RecyclerView.Adapter<SimpleAdapter.ViewHolder> {
    // Implementation with detailed comments
}

3. 🚀 Create Sample Projects

What you can do:

Build complete mini-projects for each stage
Add real-world application examples
Create practice exercises with solutions
Develop challenge projects

Project Requirements:

Complete Android Studio project
Clear README with setup instructions
Screenshots or GIFs demonstrating functionality
Comments explaining key concepts
Follows stage-appropriate complexity

Project Template:

project-name/
├── README.md                 # Project overview & instructions
├── screenshots/              # App screenshots/GIFs
├── app/                      # Complete Android project
│   ├── src/
│   ├── build.gradle
│   └── ...
└── docs/
    ├── architecture.md       # Architecture explanation
    ├── features.md           # Feature list
    └── troubleshooting.md    # Common issues

4. 🐛 Report Bugs or Issues

What you can do:

Report broken code examples
Identify outdated information
Flag incorrect explanations
Point out missing prerequisites

When reporting bugs:

Use the bug report template
Provide clear title and description
Include steps to reproduce
Add screenshots if applicable
Specify which stage/topic is affected

5. 💡 Suggest Enhancements

What you can do:

Propose new topics to cover
Suggest better explanations
Recommend useful libraries or tools
Propose restructuring for clarity

When suggesting enhancements:

Use the feature request template
Explain the problem you're solving
Describe your proposed solution
Consider alternative approaches
Mention if you're willing to implement it

6. 🌍 Translate Content

What you can do:

Translate documentation to other languages
Help maintain translated versions
Review translations for accuracy

Translation Guidelines:

Create language-specific folders: /translations/es/, /translations/fr/
Keep technical terms in English when appropriate
Maintain original formatting and structure
Update translations when source changes

7. 📚 Add Resources

What you can do:

Curate helpful articles/tutorials
Recommend YouTube channels
Share useful tools or libraries
Add interview questions
Create cheatsheets

Resource Guidelines:

Verify quality and accuracy
Ensure resources are up-to-date
Prefer free/open resources
Add brief descriptions
Organize by relevance

🚀 Getting Started

Prerequisites

Before contributing, make sure you have:

✅ Git installed
✅ GitHub account created
✅ Android Studio (for code contributions)
✅ Basic understanding of Markdown
✅ Familiarity with Android development (for technical contributions)

First-Time Setup

Fork the Repository

Click the "Fork" button at the top right of the repository page.

Clone Your Fork

git clone https://github.com/YOUR-USERNAME/android-arsenal-java.git
cd android-arsenal-java

Add Upstream Remote

git remote add upstream https://github.com/ORIGINAL-OWNER/android-arsenal-java.git

Verify Remotes

git remote -v
# origin    https://github.com/YOUR-USERNAME/android-arsenal-java.git (fetch)
# origin    https://github.com/YOUR-USERNAME/android-arsenal-java.git (push)
# upstream  https://github.com/ORIGINAL-OWNER/android-arsenal-java.git (fetch)
# upstream  https://github.com/ORIGINAL-OWNER/android-arsenal-java.git (push)

🔄 Contribution Workflow

Step 1: Sync Your Fork

Always start by syncing your fork with the upstream repository:

git checkout main
git fetch upstream
git merge upstream/main
git push origin main

Step 2: Create a Branch

Create a descriptive branch name:

git checkout -b feature/add-retrofit-example
# or
git checkout -b fix/broken-link-stage2
# or
git checkout -b docs/improve-mvvm-explanation

Branch naming conventions:

feature/ - New features or content
fix/ - Bug fixes
docs/ - Documentation improvements
refactor/ - Code refactoring
test/ - Adding tests
chore/ - Maintenance tasks

Step 3: Make Your Changes

Make focused, logical changes
Test your changes thoroughly
Follow style guidelines (see below)
Add/update documentation as needed

Step 4: Commit Your Changes

Follow our commit message guidelines:

git add .
git commit -m "feat: add Retrofit example in Stage 3"

Step 5: Push to Your Fork

git push origin feature/add-retrofit-example

Step 6: Open a Pull Request

Go to your fork on GitHub
Click "Pull Request" button
Select your branch
Fill out the PR template
Submit for review

📝 Style Guidelines

Markdown Style

Headers:

# H1 - Only once per file (title)
## H2 - Main sections
### H3 - Subsections
#### H4 - Details

Lists:

- Use hyphens for unordered lists
- Keep consistent indentation
- Add blank lines between list items for readability

1. Use numbers for ordered lists
2. Start from 1 each time
3. Let Markdown handle numbering

Code Blocks:

Use language identifiers:
```java
public class Example {
    // Java code
}

<LinearLayout>
    <!-- XML code -->
</LinearLayout>


**Links:**
```markdown
[Internal link](../path/to/file.md)
[External link](https://example.com)

Emphasis:

Use **bold** for important terms
Use *italics* for emphasis
Use `code` for inline code or commands

Emojis:

Use emojis sparingly and consistently:
🎯 Goals/Objectives
📚 Learning/Resources
💡 Tips/Notes
✅ Completed/Success
⚠️ Warnings
🚀 Getting Started/Quick Actions

Java Code Style

Follow standard Java conventions:

// ✅ GOOD
public class MainActivity extends AppCompatActivity {
    private static final String TAG = "MainActivity";
    private RecyclerView recyclerView;
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        
        initializeViews();
    }
    
    /**
     * Initializes UI components
     */
    private void initializeViews() {
        recyclerView = findViewById(R.id.recycler_view);
        // Clear, descriptive method name
    }
}

Key points:

Use meaningful variable names
Add comments for complex logic
Follow camelCase naming
Keep methods focused and small
Include JavaDoc for public methods
Use proper indentation (4 spaces)

XML Style

<!-- ✅ GOOD -->
<LinearLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    android:padding="16dp">
    
    <TextView
        android:id="@+id/title_text"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/title"
        android:textSize="20sp" />
        
</LinearLayout>

Key points:

Use proper indentation (4 spaces)
Order attributes logically
Use resource files for strings/colors
Add comments for complex layouts

File Naming

✅ GOOD:
- activity-lifecycle.md
- retrofit-example.java
- list-adapter-implementation.md
- project-setup-guide.md

❌ BAD:
- Activity Lifecycle.md (spaces)
- retrofitExample.java (wrong case)
- list_adapter.md (inconsistent separator)

Conventions:

Use lowercase
Use hyphens for spaces
Be descriptive but concise
Use appropriate file extensions

💬 Commit Message Guidelines

We follow the Conventional Commits specification.

Format

<type>(<scope>): <subject>

<body>

<footer>

Types

feat - New feature or content
fix - Bug fix
docs - Documentation changes
style - Code style/formatting (no functional changes)
refactor - Code refactoring
test - Adding tests
chore - Maintenance tasks

Examples

# ✅ GOOD
feat(stage2): add RecyclerView click listener example
fix(stage3): correct Retrofit API call implementation
docs(readme): update installation instructions
chore: update .gitignore file

# ❌ BAD
updated files
fixed bug
added stuff

Detailed Example

feat(stage4): add MVVM architecture example

- Created complete MVVM implementation
- Added ViewModel with LiveData
- Included Repository pattern
- Added unit tests for ViewModel

Closes #42

🔍 Pull Request Process

Before Submitting

Checklist:

Code compiles without errors
All tests pass (if applicable)
Documentation is updated
Changes are focused and logical
Commit messages follow guidelines
No merge conflicts with main branch
Screenshots added (for UI changes)
README updated (if adding projects)

PR Template

When you open a PR, fill out the template:

## Description
Brief description of changes

## Type of Change
- [ ] Documentation update
- [ ] Bug fix
- [ ] New feature/content
- [ ] Code refactoring
- [ ] Other (specify)

## Related Issue
Closes #(issue number)

## Testing
How has this been tested?

## Screenshots (if applicable)
Add screenshots here

## Checklist
- [ ] My code follows the style guidelines
- [ ] I have performed a self-review
- [ ] I have commented my code where needed
- [ ] My changes generate no new warnings
- [ ] I have updated the documentation

Review Process

Automated Checks
- CI/CD pipeline runs
- Linting checks pass
- Build succeeds
Manual Review
- Maintainer reviews code/content
- Feedback provided if needed
- Discussion on improvements
Approval & Merge
- PR approved by maintainer
- Merged into main branch
- Contributor credited

After Merge

Your contribution appears in the repository
You're added to contributors list
Close related issues if applicable
Celebrate! 🎉

🏆 Recognition

All contributors are recognized in:

README.md - Contributors section
GitHub Insights - Contributor graph
Release Notes - When applicable

Special Recognition:

🌟 First-time contributors get a special welcome
🏆 Top contributors featured in README
📚 Significant contributions highlighted in releases

🤔 Questions?

Before Asking

Check existing documentation
Search closed issues
Review past discussions
Read this guide thoroughly

Where to Ask

Questions: Open a Q&A Discussion
Ideas: Open a Feature Request
Bugs: Open a Bug Report
General: Join our Discord Server (if available)

📚 Additional Resources

For Contributors

For Android Development

💖 Thank You!

Your contributions make this project better for everyone. Whether you're fixing a typo, adding documentation, or building sample projects, every contribution matters.

Happy Contributing! 🚀

Back to Top | View Main README | Report an Issue

Made with ❤️ by the Android community

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

🤝 Contributing to Android-Arsenal-Java

📋 Table of Contents

📜 Code of Conduct

🎯 How Can I Contribute?

1. 📝 Improve Documentation

2. 💻 Add Code Examples

3. 🚀 Create Sample Projects

4. 🐛 Report Bugs or Issues

5. 💡 Suggest Enhancements

6. 🌍 Translate Content

7. 📚 Add Resources

🚀 Getting Started

Prerequisites

First-Time Setup

🔄 Contribution Workflow

Step 1: Sync Your Fork

Step 2: Create a Branch

Step 3: Make Your Changes

Step 4: Commit Your Changes

Step 5: Push to Your Fork

Step 6: Open a Pull Request

📝 Style Guidelines

Markdown Style

Java Code Style

XML Style

File Naming

💬 Commit Message Guidelines

Format

Types

Examples

Detailed Example

🔍 Pull Request Process

Before Submitting

PR Template

Review Process

After Merge

🏆 Recognition

🤔 Questions?

Before Asking

Where to Ask

📚 Additional Resources

For Contributors

For Android Development

💖 Thank You!