From b937ac6f08793feb25824650d2cbcbfefaea79bd Mon Sep 17 00:00:00 2001 From: Yemaneberhan-Lemma Date: Sun, 17 Nov 2024 18:29:58 +0300 Subject: [PATCH 1/2] Created the first two part of Diataxis based documentation for Contrib Tracker --- docs/how-to-guides/add-custom-source.md | 73 +++++++++++++++++++ docs/how-to-guides/generate-reports.md | 10 +++ docs/how-to-guides/how-to-work.md | 32 ++++++++ docs/how-to-guides/index.md | 21 ++++++ docs/how-to-guides/reset-social-login.md | 18 +++++ docs/how-to-guides/setting-up-social-login.md | 25 +++++++ docs/index.md | 31 ++++++++ docs/tutorials/getting-started.md | 72 ++++++++++++++++++ docs/tutorials/index.md | 7 ++ 9 files changed, 289 insertions(+) create mode 100644 docs/how-to-guides/add-custom-source.md create mode 100644 docs/how-to-guides/generate-reports.md create mode 100644 docs/how-to-guides/how-to-work.md create mode 100644 docs/how-to-guides/index.md create mode 100644 docs/how-to-guides/reset-social-login.md create mode 100644 docs/how-to-guides/setting-up-social-login.md create mode 100644 docs/tutorials/getting-started.md create mode 100644 docs/tutorials/index.md diff --git a/docs/how-to-guides/add-custom-source.md b/docs/how-to-guides/add-custom-source.md new file mode 100644 index 00000000..3874779b --- /dev/null +++ b/docs/how-to-guides/add-custom-source.md @@ -0,0 +1,73 @@ +# Adding and Customizing a Contribution Source + +The Contribution Tracker supports tracking contributions from various data sources through custom plugins. This guide explains how to add a new contribution source, including creating and configuring the plugin and managing any necessary database adjustments. + +## Steps to Add and Customize a Contribution Source + +1. **Understand the Contribution Plugin System** + - Contribution sources are implemented as plugins of type `ContributionSource` in the Contribution Plugin Manager. + - Each plugin retrieves and processes contributions for its source during cron runs. + +2. **Configure the New Data Source** + - Identify the API or database schema for the source you wish to integrate. + - Ensure you have access credentials, such as tokens or API keys, for secure integration. + +3. **Create the Custom Plugin** + - **File Location**: Place the plugin in the `src/Plugin/ContributionSource` directory of your custom module. + - **Plugin Annotation**: Use the `@ContributionSource` annotation to define the plugin, like this: + + ```php + /** + * @ContributionSource( + * id = "custom_source", + * description = @Translation("Retrieve contributions from Custom Source.") + * ) + */ + ``` + + - **Implement the Interface**: Ensure the plugin implements the `ContributionSourceInterface` and its required methods: + - `process()`: Fetch and process contributions. + - `getUserIssues()` and `getUserCodeContributions()`: Handle data retrieval for user contributions. + +4. **Adjust the Database if Necessary** + - Review the existing schema to determine if additional fields or tables are needed for the new data source. + - Use Drupal’s schema API to add custom tables or fields. + +5. **Test the Plugin** + - Use test data or sandbox API credentials to validate the plugin. + - Ensure contributions are retrieved and processed correctly without errors. + +6. **Integrate with the Contribution Tracker** + - Enable the plugin in the Contribution Tracker configuration. + - Run cron to test how contributions from the new source are tracked. + +### Example: Creating a Plugin for Custom API Source + +- **File Path**: `custom_module/src/Plugin/ContributionSource/CustomSource.php` +- **Sample Code**: + + ```php + namespace Drupal\custom_module\Plugin\ContributionSource; + + use Drupal\ct_manager\ContributionSourceInterface; + + /** + * @ContributionSource( + * id = "custom_source", + * description = @Translation("Retrieve contributions from a custom API.") + * ) + */ + class CustomSource implements ContributionSourceInterface { + public function process() { + // Custom logic to fetch and process contributions. + } + + public function getUserIssues() { + // Fetch user issues from the API. + } + + public function getUserCodeContributions() { + // Fetch user code contributions from the API. + } + } + ``` diff --git a/docs/how-to-guides/generate-reports.md b/docs/how-to-guides/generate-reports.md new file mode 100644 index 00000000..9f23435e --- /dev/null +++ b/docs/how-to-guides/generate-reports.md @@ -0,0 +1,10 @@ +# Generating Contribution Reports + +1. **Access Reports** + Navigate to `/contribution-count` for Contribution Count reports. + +2. **Customize Reports** + - Filter by contribution type, technology, contributor name, etc. + +3. **Export Data** + - Export reports in CSV or other formats for external analysis. diff --git a/docs/how-to-guides/how-to-work.md b/docs/how-to-guides/how-to-work.md new file mode 100644 index 00000000..26932cf6 --- /dev/null +++ b/docs/how-to-guides/how-to-work.md @@ -0,0 +1,32 @@ +# How to work on this project + +Before committing your changes, make sure you are working on the latest codebase by fetching or pulling to make sure you have all the work. + +```bash +git checkout main +git pull origin main +``` + +To initiate a build: + + 1. Create a branch specific to the feature. + + ```bash + git checkout -b + ``` + + 2. Make the required changes and commit + + ```bash + git commit -m "commit-message" + ``` + + 3. Push the changes + + ```bash + git push origin + ``` + +For a better understanding of the entire process and standards, please refer to Axelerant's [Git workflow.](https://engg-handbook.axelerant.com/docs/how-we-work/git/git-workflow/) + +N.B. If provided with a user account, you can use the management console of [platform.sh](https://platform.sh/) to handle your branch-merge requests. Please refer to the official [documentation](https://docs.platform.sh/frameworks/drupal8/developing-with-drupal.html#merge-code-changes-to-master) for further information. diff --git a/docs/how-to-guides/index.md b/docs/how-to-guides/index.md new file mode 100644 index 00000000..9c141f96 --- /dev/null +++ b/docs/how-to-guides/index.md @@ -0,0 +1,21 @@ +# How-to Guides + +This section provides practical, task-oriented guides for working with the Contribution Tracker system. + +- [How to Work on This Project](how-to-work.md) + - Steps for working with the latest code, committing changes, and managing branches + +- [Adding a New Contribution Source](add-custom-source.md) + - Steps to Add and Customize a Contribution Source + +- [Generating Contribution Reports](generate-reports.md) + - How to create, customize, and export reports. + +- [Setting Up Social Login Integration](setting-up-social-login.md) + - Overview of supported social login options. + - Configuring and testing GitHub and Drupal.org social logins. + +- [Resetting Social Login and Authentication Settings](reset-social-login.md) + - Troubleshooting and reconfiguring social login providers. + +For foundational guides, visit the [Tutorials section](../tutorials/index.md). diff --git a/docs/how-to-guides/reset-social-login.md b/docs/how-to-guides/reset-social-login.md new file mode 100644 index 00000000..74494095 --- /dev/null +++ b/docs/how-to-guides/reset-social-login.md @@ -0,0 +1,18 @@ +# Resetting Social Login and Authentication Settings + +## Troubleshooting Common Issues + +1. **Expired Tokens**: + - Renew OAuth credentials via the provider's dashboard. + +2. **Invalid Configuration**: + - Check for typos or mismatched URLs in the settings. + - Verify `redirect_uri` matches the settings on the provider side. + +## Steps for Resetting + +1. **Reconfigure OAuth Settings**: + - Update client ID and secret in `settings.php`. + +2. **Re-test Integration**: + - Use the testing steps from the *Setting Up Social Login Integration* guide to confirm fixes. diff --git a/docs/how-to-guides/setting-up-social-login.md b/docs/how-to-guides/setting-up-social-login.md new file mode 100644 index 00000000..b5a6875f --- /dev/null +++ b/docs/how-to-guides/setting-up-social-login.md @@ -0,0 +1,25 @@ +# Setting Up Social Login Integration + +Streamline user authentication by enabling social login for GitHub and Drupal.org. This enhances usability while maintaining security. + +## Step-by-Step Configuration + +1. **Prepare OAuth Credentials**: + - GitHub: Create an OAuth application via [GitHub Developer Settings](https://github.com/settings/developers). + - Drupal.org: Set up API access via your Drupal.org account. + +2. **Add Credentials to System Settings**: + - Update `settings.php` with the obtained client ID and secret for each provider: + + ```php + $settings['github']['client_id'] = 'YOUR_CLIENT_ID'; + $settings['github']['client_secret'] = 'YOUR_CLIENT_SECRET'; + ``` + +3. **Enable Social Login Modules**: + - Ensure the necessary modules (`social_auth_github`, `social_auth_drupal`) are enabled. + +**Testing and Verification** + +- Test logins with dummy accounts to confirm functionality. +- Check for errors in the logs or use debugging tools if issues arise. diff --git a/docs/index.md b/docs/index.md index de5d2f2e..219f619d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,34 @@ # Overview The Contribution Tracking System is designed to facilitate the monitoring and analysis of contributions across various projects and initiatives within our organization. Leveraging the power of Drupal, this system provides robust features for capturing, categorizing, and reporting on our contributions, thereby enabling better resource allocation, performance evaluation, and recognition of employee achievements. + +## 1. [Tutorials](tutorials/index.md) + +Step-by-step guides to help you get started with the Contribution Tracker. + +- [Getting Started with Contribution Tracker](tutorials/getting-started.md) + +## 2. [How-to Guides](how-to-guides/index.md) + +Practical solutions for common tasks in the Contribution Tracker. + +- [How to Work on This Project](how-to-guides/how-to-work.md) +- [Adding a New Contribution Source](how-to-guides/add-custom-source.md) +- [Generating Contribution Reports](how-to-guides/generate-reports.md) +- [Setting Up Social Login Integration](how-to-guides/setting-up-social-login.md) +- [Resetting Social Login and Authentication Settings](how-to-guides/reset-authentication.md) + +## 3. References + +Technical resources and detailed information about the Contribution Tracker. + +- Codebase Overview and Key Components +- API Documentation +- Contribution Plugin Manager Module + +## 4. Explanations + +Insights into the architecture, design choices, and inner workings of the Contribution Tracker. + +- Architecture and Design Choices +- How Contribution Tracking Works diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started.md new file mode 100644 index 00000000..ed74cee9 --- /dev/null +++ b/docs/tutorials/getting-started.md @@ -0,0 +1,72 @@ +# Getting Started with Contribution Tracker + +## Overview + +The Contribution Tracking System monitors and analyzes contributions across projects, leveraging Drupal’s features for capturing, categorizing, and reporting data. It aids in resource allocation, performance evaluation, and recognizing achievements. + +## Tools & Prerequisites + +Major tools that are required for setting up the site. It is recommended to use the latest version or at least the minimum version as mentioned below. It is mandatory to add [your SSH key to your GitHub account settings](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account). + +- [Composer](https://getcomposer.org/download/) (optional if used via DDEV) + +- [Docker](https://docs.docker.com/install/) or [OrbStack](https://orbstack.dev/) + +- [DDEV](https://ddev.com/get-started/) - v1.22.0 + +- [NodeJs](https://nodejs.org/en/download) + +## Local environment setup + +Once you have all the tools installed, proceed to run the following to clone the repository. + +```bash +git clone git@github.com:contrib-tracker/backend.git +``` + +Change to the directory of the repository and run DDEV to start. + +```bash +cd backend +ddev start +``` + +Once DDEV has been set up successfully, it will display the links in the terminal. Next, run the following to fetch all dependencies. + +```bash +ddev composer install +``` + +You can pull the database from the platform.sh directly. Make sure that the [PLATFORMSH_CLI_TOKEN is set](https://ddev.readthedocs.io/en/latest/users/providers/platform/). + +```bash +ddev pull platform +``` + +Make sure code changes are updated. + +```bash +ddev drush deploy -y +``` + +## Post Installation + +Generate a one-time login link and reset the password through it. + +```bash +ddev drush uli +``` + +Clear the cache using drush + +```bash +ddev drush cr +``` + +## Theme Build + +```bash +cd web/themes/custom/contribtracker && npm install && npm run build && ddev drush cr +``` + +You can access the site at: [https://contribtracker.ddev.site/](https://contribtracker.ddev.site/). diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md new file mode 100644 index 00000000..83146143 --- /dev/null +++ b/docs/tutorials/index.md @@ -0,0 +1,7 @@ +# Tutorials + +Welcome to the Tutorials section of the Contribution Tracker documentation. These step-by-step guides introduce core concepts and workflows, helping new contributors get started quickly. + +- [Getting Started with Contribution Tracker](getting-started.md) + - Overview of the system, its purpose, and core features. + - Setting up the local environment and installing dependencies. From 74837129b627ee5b5fbb76185ab534c023d5fc74 Mon Sep 17 00:00:00 2001 From: Yemaneberhan-Lemma Date: Mon, 16 Dec 2024 22:13:48 +0300 Subject: [PATCH 2/2] Made changes as per comments --- docs/how-to-guides/add-custom-source.md | 2 +- docs/how-to-guides/how-to-work.md | 2 +- docs/how-to-guides/reset-social-login.md | 4 ++-- docs/tutorials/getting-started.md | 8 ++++---- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/how-to-guides/add-custom-source.md b/docs/how-to-guides/add-custom-source.md index 3874779b..df5bd031 100644 --- a/docs/how-to-guides/add-custom-source.md +++ b/docs/how-to-guides/add-custom-source.md @@ -5,7 +5,7 @@ The Contribution Tracker supports tracking contributions from various data sourc ## Steps to Add and Customize a Contribution Source 1. **Understand the Contribution Plugin System** - - Contribution sources are implemented as plugins of type `ContributionSource` in the Contribution Plugin Manager. + - Contribution sources are implemented as plugins of type `ContributionSource` in the [Contribution Plugin Manager](../../web/modules/custom/ct_manager). - Each plugin retrieves and processes contributions for its source during cron runs. 2. **Configure the New Data Source** diff --git a/docs/how-to-guides/how-to-work.md b/docs/how-to-guides/how-to-work.md index 26932cf6..48a66cb5 100644 --- a/docs/how-to-guides/how-to-work.md +++ b/docs/how-to-guides/how-to-work.md @@ -29,4 +29,4 @@ To initiate a build: For a better understanding of the entire process and standards, please refer to Axelerant's [Git workflow.](https://engg-handbook.axelerant.com/docs/how-we-work/git/git-workflow/) -N.B. If provided with a user account, you can use the management console of [platform.sh](https://platform.sh/) to handle your branch-merge requests. Please refer to the official [documentation](https://docs.platform.sh/frameworks/drupal8/developing-with-drupal.html#merge-code-changes-to-master) for further information. +N.B. If provided with a user account, you can use the management console of Platform.sh to manage your environment and deployments. diff --git a/docs/how-to-guides/reset-social-login.md b/docs/how-to-guides/reset-social-login.md index 74494095..e91d8fc0 100644 --- a/docs/how-to-guides/reset-social-login.md +++ b/docs/how-to-guides/reset-social-login.md @@ -12,7 +12,7 @@ ## Steps for Resetting 1. **Reconfigure OAuth Settings**: - - Update client ID and secret in `settings.php`. + - Update the client ID and secret using environment variables in Platform.sh. Ensure the correct values are set for your project’s environment configuration. 2. **Re-test Integration**: - - Use the testing steps from the *Setting Up Social Login Integration* guide to confirm fixes. + - Follow the testing steps outlined in the [Setting Up Social Login Integration guide](setting-up-social-login.md) to confirm that the changes are working correctly. diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started.md index ed74cee9..a701f1b9 100644 --- a/docs/tutorials/getting-started.md +++ b/docs/tutorials/getting-started.md @@ -8,13 +8,13 @@ The Contribution Tracking System monitors and analyzes contributions across proj Major tools that are required for setting up the site. It is recommended to use the latest version or at least the minimum version as mentioned below. It is mandatory to add [your SSH key to your GitHub account settings](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account). -- [Composer](https://getcomposer.org/download/) (optional if used via DDEV) +- [OrbStack](https://orbstack.dev/) or [Docker](https://docs.docker.com/install/) -- [Docker](https://docs.docker.com/install/) or [OrbStack](https://orbstack.dev/) +- [Composer](https://getcomposer.org/download/) (optional if used via DDEV) -- [DDEV](https://ddev.com/get-started/) - v1.22.0 +- [DDEV](https://ddev.com/get-started/) - v1.23.3 and above. -- [NodeJs](https://nodejs.org/en/download) +- [NodeJs](https://nodejs.org/en/download) (optional if used via DDEV) ## Local environment setup