From 3bbf96e49599d2a52210cc56228bd9fa73087beb Mon Sep 17 00:00:00 2001 From: Mrugesh Mohapatra <1884376+raisedadead@users.noreply.github.com> Date: Wed, 10 Feb 2021 16:20:14 +0530 Subject: [PATCH] chore: update devops docs (#41037) --- SECURITY.md | 12 +++---- docs/devops.md | 66 +++++++++++++++++++------------------- docs/moderator-handbook.md | 20 ++++++------ 3 files changed, 49 insertions(+), 49 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index 0f9ad89ee2..9aef5db8b4 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -4,15 +4,15 @@ This document outlines our security policy for the codebase, and how to report v ## Versions -| Version | Branch | Supported | Website active | -| ----------- | ------------------------ | ------------------ | ---------------- | -| production | `production-current` | :white_check_mark: | freecodecamp.org | -| beta | `production-staging` | :white_check_mark: | freecodecamp.dev | -| development | `master` | | | +| Version | Branch | Supported | Website active | +| ----------- | -------------- | ------------------ | ---------------- | +| production | `prod-current` | :white_check_mark: | freecodecamp.org | +| beta | `prod-staging` | :white_check_mark: | freecodecamp.dev | +| development | `main` | | | ## Reporting a Vulnerability -If you think you have found a vulnerability, *please report responsibly*. Don't create GitHub issues for security issues. Instead, please send an email to `security@freecodecamp.org` and we'll look into it immediately. +If you think you have found a vulnerability, _please report responsibly_. Don't create GitHub issues for security issues. Instead, please send an email to `security@freecodecamp.org` and we'll look into it immediately. We appreciate any responsible disclosure of vulnerabilities that might impact the integrity of our platforms and users. While we do not offer any bounties or swags at the moment, we'll be happy to list your name in our [Hall of Fame](HoF.md) list. diff --git a/docs/devops.md b/docs/devops.md index 743c2440b0..385fc447e5 100644 --- a/docs/devops.md +++ b/docs/devops.md @@ -16,13 +16,13 @@ This involves three steps to be followed in sequence: #### Building the codebase - Mapping Git Branches to Deployments. -Typically, [`main`](https://github.com/freeCodeCamp/freeCodeCamp/tree/main) (the default development branch) is merged into the [`production-staging`](https://github.com/freeCodeCamp/freeCodeCamp/tree/production-staging) branch once a day and is released into an isolated infrastructure. +Typically, [`main`](https://github.com/freeCodeCamp/freeCodeCamp/tree/main) (the default development branch) is merged into the [`prod-staging`](https://github.com/freeCodeCamp/freeCodeCamp/tree/prod-staging) branch once a day and is released into an isolated infrastructure. This is an intermediate release for our developers and volunteer contributors. It is also known as our "staging" or "beta" release. It is identical to our live production environment at `freeCodeCamp.org`, other than it using a separate set of databases, servers, web-proxies, etc. This isolation lets us test ongoing development and features in a "production" like scenario, without affecting regular users of freeCodeCamp.org's main platforms. -Once the developer team [`@freeCodeCamp/dev-team`](https://github.com/orgs/freeCodeCamp/teams/dev-team/members) is happy with the changes on the staging platform, these changes are moved every few days to the [`production-current`](https://github.com/freeCodeCamp/freeCodeCamp/tree/production-current) branch. +Once the developer team [`@freeCodeCamp/dev-team`](https://github.com/orgs/freeCodeCamp/teams/dev-team/members) is happy with the changes on the staging platform, these changes are moved every few days to the [`prod-current`](https://github.com/freeCodeCamp/freeCodeCamp/tree/prod-current) branch. This is the final release that moves changes to our production platforms on freeCodeCamp.org. @@ -99,10 +99,10 @@ Currently, only members on the developer team can push to the production branche npm run clean-and-develop ``` -5. Move changes from `main` to `production-staging` via a fast-forward merge +5. Move changes from `main` to `prod-staging` via a fast-forward merge ``` - git checkout production-staging + git checkout prod-staging git merge main git push upstream ``` @@ -112,13 +112,10 @@ Currently, only members on the developer team can push to the production branche > > If they do, you may have done something incorrectly and you should just start over. -The above steps will automatically trigger a run on the build pipeline for the `production-staging` branch. Once the build is complete, the artifacts are saved as `.zip` files in a cold storage to be retrieved and used later. +The above steps will automatically trigger a run on the build pipeline for the `prod-staging` branch. Once the build is complete, the artifacts are saved as `.zip` files in a cold storage to be retrieved and used later. The release pipeline is triggered automatically when a fresh artifact is available from the connected build pipeline. For staging platforms, this process does not involve manual approval and the artifacts are pushed to the Client CDN and API servers. -> [!TIP|label:Estimates] -> Typically the build run takes ~20-25 minutes to complete followed by the release run which takes ~15-20 mins for the client, and ~5-10 mins for the API to be available live. From code push to being live on the staging platforms the whole process takes **~35-45 mins** in total. - ### Pushing changes to Production Applications. The process is mostly the same as the staging platforms, with a few extra checks in place. This is just to make sure, we do not break anything on freeCodeCamp.org which can see hundreds of users using it at any moment. @@ -127,19 +124,19 @@ The process is mostly the same as the staging platforms, with a few extra checks | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -1. Make sure your `production-staging` branch is pristine and in sync with the upstream. +1. Make sure your `prod-staging` branch is pristine and in sync with the upstream. ```sh - git checkout production-staging + git checkout prod-staging git fetch --all --prune - git reset --hard upstream/production-staging + git reset --hard upstream/prod-staging ``` -2. Move changes from `production-staging` to `production-current` via a fast-forward merge +2. Move changes from `prod-staging` to `prod-current` via a fast-forward merge ``` - git checkout production-current - git merge production-staging + git checkout prod-current + git merge prod-staging git push upstream ``` @@ -148,10 +145,7 @@ The process is mostly the same as the staging platforms, with a few extra checks > > If they do, you may have done something incorrectly and you should just start over. -The above steps will automatically trigger a run on the build pipeline for the `production-current` branch. Once a build artifact is ready, it will trigger a run on the release pipeline. - -> [!TIP|label:Estimates] -> Typically the build run takes ~20-25 minutes to complete. +The above steps will automatically trigger a run on the build pipeline for the `prod-current` branch. Once a build artifact is ready, it will trigger a run on the release pipeline. **Additional Steps for Staff Action** @@ -165,22 +159,18 @@ For staff use: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -Once one of the staff members approves a release, the pipeline will push the changes live to freeCodeCamp.org's production CDN and API servers. They typically take ~15-20 mins for the client, and ~5 mins for the API servers to be available live. - -> [!TIP|label:Estimates] -> The release run typically takes ~15-20 mins for each client instance, and ~5-10 mins for each API instance to be available live. From code push to being live on the production platforms the whole process takes **~90-120 mins** in total (not counting the wait time for the staff approval). +Once one of the staff members approves a release, the pipeline will push the changes live to freeCodeCamp.org's production CDN and API servers. ## Build, Test and Deployment Status Here is the current test, build and deployment status of the codebase. -| Type | Branch | Status | Dashboard | -| :--------------- | :------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------- | -| Build Pipeline | [`production-staging`](https://github.com/freeCodeCamp/freeCodeCamp/tree/production-staging) | [![Build Status](https://dev.azure.com/freeCodeCamp-org/freeCodeCamp/_apis/build/status/dot-dev-ci?branchName=production-staging)](https://dev.azure.com/freeCodeCamp-org/freeCodeCamp/_build/latest?definitionId=15&branchName=production-staging) | [Go to status dashboard](https://dev.azure.com/freeCodeCamp-org/freeCodeCamp/_build) | -| Release Pipeline | [`production-staging`](https://github.com/freeCodeCamp/freeCodeCamp/tree/production-staging) | | [Go to status dashboard](https://dev.azure.com/freeCodeCamp-org/freeCodeCamp/_release) | -| CI Tests | [`production-current`](https://github.com/freeCodeCamp/freeCodeCamp/tree/production-current) | ![Travis CI Build Status](https://travis-ci.com/freeCodeCamp/freeCodeCamp.svg?branch=production-current) | [Go to status dashboard](https://travis-ci.com/github/freeCodeCamp/freeCodeCamp/branches) | -| Build Pipeline | [`production-current`](https://github.com/freeCodeCamp/freeCodeCamp/tree/production-staging) | [![Build Status](https://dev.azure.com/freeCodeCamp-org/freeCodeCamp/_apis/build/status/dot-org-ci?branchName=production-current)](https://dev.azure.com/freeCodeCamp-org/freeCodeCamp/_build/latest?definitionId=17&branchName=production-current) | [Go to status dashboard](https://dev.azure.com/freeCodeCamp-org/freeCodeCamp/_build) | -| Release Pipeline | [`production-current`](https://github.com/freeCodeCamp/freeCodeCamp/tree/production-staging) | | [Go to status dashboard](https://dev.azure.com/freeCodeCamp-org/freeCodeCamp/_release) | +| Branch | Unit Tests | Integration Tests | Builds & Deployments | +| :------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- | +| [`main`](https://github.com/freeCodeCamp/freeCodeCamp/tree/main) | [![Node.js CI](https://github.com/freeCodeCamp/freeCodeCamp/workflows/Node.js%20CI/badge.svg?branch=main)](https://github.com/freeCodeCamp/freeCodeCamp/actions?query=workflow%3A%22Node.js+CI%22) | [![Cypress E2E Tests](https://img.shields.io/endpoint?url=https://dashboard.cypress.io/badge/simple/ke77ns/main&style=flat&logo=cypress)](https://dashboard.cypress.io/projects/ke77ns/analytics/runs-over-time) | - | +| [`prod-staging`](https://github.com/freeCodeCamp/freeCodeCamp/tree/prod-staging) | [![Node.js CI](https://github.com/freeCodeCamp/freeCodeCamp/workflows/Node.js%20CI/badge.svg?branch=prod-staging)](https://github.com/freeCodeCamp/freeCodeCamp/actions?query=workflow%3A%22Node.js+CI%22+branch%3Aprod-staging) | [![Cypress E2E Tests](https://img.shields.io/endpoint?url=https://dashboard.cypress.io/badge/simple/ke77ns/prod-staging&style=flat&logo=cypress)](https://dashboard.cypress.io/projects/ke77ns/analytics/runs-over-time) | [Azure Pipelines](https://dev.azure.com/freeCodeCamp-org/freeCodeCamp/_dashboards/dashboard/d59f36b9-434a-482d-8dbd-d006b71713d4) | +| [`prod-current`](https://github.com/freeCodeCamp/freeCodeCamp/tree/prod-staging) | [![Node.js CI](https://github.com/freeCodeCamp/freeCodeCamp/workflows/Node.js%20CI/badge.svg?branch=prod-current)](https://github.com/freeCodeCamp/freeCodeCamp/actions?query=workflow%3A%22Node.js+CI%22+branch%3Aprod-current) | [![Cypress E2E Tests](https://img.shields.io/endpoint?url=https://dashboard.cypress.io/badge/simple/ke77ns/prod-current&style=flat&logo=cypress)](https://dashboard.cypress.io/projects/ke77ns/analytics/runs-over-time) | [Azure Pipelines](https://dev.azure.com/freeCodeCamp-org/freeCodeCamp/_dashboards/dashboard/d59f36b9-434a-482d-8dbd-d006b71713d4) | +| `prod-next` (experimental, upcoming) | - | - | - | ## Early access and beta testing @@ -194,16 +184,26 @@ We thank you for reporting bugs that you encounter and help in making freeCodeCa Currently a public beta testing version is available at: -

freecodecamp.dev

+| Application | Language | URL | +| :---------- | :------- | :--------------------------------------- | +| Learn | English | | +| | Espanol | | +| | Chinese | | +| News | English | | +| Forum | English | | +| | Chinese | | +| API | - | `https://api.freecodecamp.dev` | > [!NOTE] > The domain name is different than **`freeCodeCamp.org`**. This is intentional to prevent search engine indexing and avoid confusion for regular users of the platform. +> +> The above list not exhaustive of all the applications that we provision. Also not all language variants are deployed in staging to conserve resources. ### Identifying the current version of the platforms **The current version of the platform is always available at [`freeCodeCamp.org`](https://www.freecodecamp.org).** -The dev-team merges changes from the `production-staging` branch to `production-current` when they release changes. The top commit should be what you see live on the site. +The dev-team merges changes from the `prod-staging` branch to `prod-current` when they release changes. The top commit should be what you see live on the site. You can identify the exact version deployed by visiting the build and deployment logs available in the status section. Alternatively you can also ping us in the [contributors chat room](https://chat.freecodecamp.org/channel/contributors) for a confirmation. @@ -229,7 +229,7 @@ There are some known limitations and tradeoffs when using the beta version of th ## Reporting issues and leaving feedback -Please open fresh issues for discussions and reporting bugs. You can label them as **[`release: next/beta`](https://github.com/freeCodeCamp/freeCodeCamp/labels/release%3A%20next%2Fbeta)** for triage. +Please open fresh issues for discussions and reporting bugs. You may send an email to `dev[at]freecodecamp.org` if you have any queries. As always all security vulnerabilities should be reported to `security[at]freecodecamp.org` instead of the public tracker and forum. @@ -565,7 +565,7 @@ Provisioning VMs with the Code ```console git clone https://github.com/freeCodeCamp/freeCodeCamp.git cd freeCodeCamp - git checkout production-current # or any other branch to be deployed + git checkout prod-current # or any other branch to be deployed ``` 4. Create the `.env` from the secure credentials storage. diff --git a/docs/moderator-handbook.md b/docs/moderator-handbook.md index 3906c79d61..21718c96fb 100644 --- a/docs/moderator-handbook.md +++ b/docs/moderator-handbook.md @@ -42,9 +42,9 @@ Pull Requests (PRs) are how contributors submit changes to freeCodeCamp's reposi ```markdown Thank you for your pull request. - + We are closing this pull request. Please add links and other details to the challenge's corresponding guide article instead. - + If you think we're wrong in closing this issue, please request for it to be reopened and add further clarification. Thank you, and happy coding. ``` @@ -80,7 +80,7 @@ In both of these situations, you should go ahead and close their pull request an ```markdown Thank you for opening this pull request. - + This is a standard message notifying you that we've reviewed your pull request and have decided not to merge it. We would welcome future pull requests from you. Thank you and happy coding. @@ -229,9 +229,9 @@ Discord Bans are global - you cannot ban a user from a specific channel, only fr There may be situations where you need to address a concern with a camper privately. This should not be done through DMs, as this can lead to situations where you claim one thing and the camper claims another. Instead, use the bot's functionality to create a private discussion: -- Call the `!fCC moderate private @username` command, where `@username` is the *Discord mention* of the user. If you are calling this command from a private channel (such as #mod-chat), you will need to parse the mention manually: Ensure you have Developer Mode turned on in your Discord settings, then right-click on the user's avatar and select `Copy ID`. Replace the `@username` parameter with `<@!ID>`, where `ID` is the value you copied earlier. The result should look like: `!fCC moderate private <@!465650873650118659>`. +- Call the `!fCC moderate private @username` command, where `@username` is the _Discord mention_ of the user. If you are calling this command from a private channel (such as #mod-chat), you will need to parse the mention manually: Ensure you have Developer Mode turned on in your Discord settings, then right-click on the user's avatar and select `Copy ID`. Replace the `@username` parameter with `<@!ID>`, where `ID` is the value you copied earlier. The result should look like: `!fCC moderate private <@!465650873650118659>`. - The bot will create a new channel under the `private` category and add the `@username`-mentioned camper and all moderators with the `Your Friendly Moderator` role. While all moderators are added to the channel for transparency, the moderator who calls this command should be the only one to interact with the camper unless they request assistance. -- When the conversation is complete, call the `!fCC moderate close` command *in the private channel* to have the bot close and delete that channel. +- When the conversation is complete, call the `!fCC moderate close` command _in the private channel_ to have the bot close and delete that channel. 4. **Deleting messages** Moderators have the ability to delete messages on Discord. They should only exercise this ability in four very specific situations: @@ -280,11 +280,11 @@ In all other situations - even situations where the code of conduct is violated Moderating the chat server is very similar to moderating the Discord server, but there are a few key differences: 1. **No Ban functionality** - At this time, Rocket.Chat does not have a flow for banning users. Users can be muted (so they are prevented from chatting in a room) or kicked from a room. + At this time, Rocket.Chat does not have a flow for banning users. Users can be muted (so they are prevented from chatting in a room) or kicked from a room. 2. **Modified Bot Commands** - The moderation bot in the chat server was developed with a smoother UX in mind. Some of the commands have been modified. Use the `!fCC modHelp` command to view the available functionality. Bot commands in the chat server do NOT require a user mention as they do with Discord. + The moderation bot in the chat server was developed with a smoother UX in mind. Some of the commands have been modified. Use the `!fCC modHelp` command to view the available functionality. Bot commands in the chat server do NOT require a user mention as they do with Discord. 3. **No Role Mentions** - Unlike Discord, Rocket.Chat does not allow you to mention all users by a specific role - this means you cannot ping all moderators at once. + Unlike Discord, Rocket.Chat does not allow you to mention all users by a specific role - this means you cannot ping all moderators at once. ## How to become a moderator @@ -380,14 +380,14 @@ Feel free to reference the [contributing guidelines](https://contribute.freecode ### Syncing Fork -> When PR is not up to date with the `master` branch. +> When PR is not up to date with the `main` branch. ````markdown Hey @username We would love to be able to merge your changes but it looks like the branch is not up to date. ⚠️ -To resolve this error, you will have to sync the latest changes from the `master` branch of the `freeCodeCamp/freeCodeCamp` repo. +To resolve this error, you will have to sync the latest changes from the `main` branch of the `freeCodeCamp/freeCodeCamp` repo. Using the command line, you can do this in three easy steps: