15 skills found
ManojKumarPatnaik / Major Project ListA list of practical projects that anyone can solve in any programming language (See solutions). These projects are divided into multiple categories, and each category has its own folder. To get started, simply fork this repo. CONTRIBUTING See ways of contributing to this repo. You can contribute solutions (will be published in this repo) to existing problems, add new projects, or remove existing ones. Make sure you follow all instructions properly. Solutions You can find implementations of these projects in many other languages by other users in this repo. Credits Problems are motivated by the ones shared at: Martyr2’s Mega Project List Rosetta Code Table of Contents Numbers Classic Algorithms Graph Data Structures Text Networking Classes Threading Web Files Databases Graphics and Multimedia Security Numbers Find PI to the Nth Digit - Enter a number and have the program generate PI up to that many decimal places. Keep a limit to how far the program will go. Find e to the Nth Digit - Just like the previous problem, but with e instead of PI. Enter a number and have the program generate e up to that many decimal places. Keep a limit to how far the program will go. Fibonacci Sequence - Enter a number and have the program generate the Fibonacci sequence to that number or to the Nth number. Prime Factorization - Have the user enter a number and find all Prime Factors (if there are any) and display them. Next Prime Number - Have the program find prime numbers until the user chooses to stop asking for the next one. Find Cost of Tile to Cover W x H Floor - Calculate the total cost of the tile it would take to cover a floor plan of width and height, using a cost entered by the user. Mortgage Calculator - Calculate the monthly payments of a fixed-term mortgage over given Nth terms at a given interest rate. Also, figure out how long it will take the user to pay back the loan. For added complexity, add an option for users to select the compounding interval (Monthly, Weekly, Daily, Continually). Change Return Program - The user enters a cost and then the amount of money given. The program will figure out the change and the number of quarters, dimes, nickels, pennies needed for the change. Binary to Decimal and Back Converter - Develop a converter to convert a decimal number to binary or a binary number to its decimal equivalent. Calculator - A simple calculator to do basic operators. Make it a scientific calculator for added complexity. Unit Converter (temp, currency, volume, mass, and more) - Converts various units between one another. The user enters the type of unit being entered, the type of unit they want to convert to, and then the value. The program will then make the conversion. Alarm Clock - A simple clock where it plays a sound after X number of minutes/seconds or at a particular time. Distance Between Two Cities - Calculates the distance between two cities and allows the user to specify a unit of distance. This program may require finding coordinates for the cities like latitude and longitude. Credit Card Validator - Takes in a credit card number from a common credit card vendor (Visa, MasterCard, American Express, Discoverer) and validates it to make sure that it is a valid number (look into how credit cards use a checksum). Tax Calculator - Asks the user to enter a cost and either a country or state tax. It then returns the tax plus the total cost with tax. Factorial Finder - The Factorial of a positive integer, n, is defined as the product of the sequence n, n-1, n-2, ...1, and the factorial of zero, 0, is defined as being 1. Solve this using both loops and recursion. Complex Number Algebra - Show addition, multiplication, negation, and inversion of complex numbers in separate functions. (Subtraction and division operations can be made with pairs of these operations.) Print the results for each operation tested. Happy Numbers - A happy number is defined by the following process. Starting with any positive integer, replace the number by the sum of the squares of its digits, and repeat the process until the number equals 1 (where it will stay), or it loops endlessly in a cycle which does not include 1. Those numbers for which this process ends in 1 are happy numbers, while those that do not end in 1 are unhappy numbers. Display an example of your output here. Find the first 8 happy numbers. Number Names - Show how to spell out a number in English. You can use a preexisting implementation or roll your own, but you should support inputs up to at least one million (or the maximum value of your language's default bounded integer type if that's less). Optional: Support for inputs other than positive integers (like zero, negative integers, and floating-point numbers). Coin Flip Simulation - Write some code that simulates flipping a single coin however many times the user decides. The code should record the outcomes and count the number of tails and heads. Limit Calculator - Ask the user to enter f(x) and the limit value, then return the value of the limit statement Optional: Make the calculator capable of supporting infinite limits. Fast Exponentiation - Ask the user to enter 2 integers a and b and output a^b (i.e. pow(a,b)) in O(LG n) time complexity. Classic Algorithms Collatz Conjecture - Start with a number n > 1. Find the number of steps it takes to reach one using the following process: If n is even, divide it by 2. If n is odd, multiply it by 3 and add 1. Sorting - Implement two types of sorting algorithms: Merge sort and bubble sort. Closest pair problem - The closest pair of points problem or closest pair problem is a problem of computational geometry: given n points in metric space, find a pair of points with the smallest distance between them. Sieve of Eratosthenes - The sieve of Eratosthenes is one of the most efficient ways to find all of the smaller primes (below 10 million or so). Graph Graph from links - Create a program that will create a graph or network from a series of links. Eulerian Path - Create a program that will take as an input a graph and output either an Eulerian path or an Eulerian cycle, or state that it is not possible. An Eulerian path starts at one node and traverses every edge of a graph through every node and finishes at another node. An Eulerian cycle is an eulerian Path that starts and finishes at the same node. Connected Graph - Create a program that takes a graph as an input and outputs whether every node is connected or not. Dijkstra’s Algorithm - Create a program that finds the shortest path through a graph using its edges. Minimum Spanning Tree - Create a program that takes a connected, undirected graph with weights and outputs the minimum spanning tree of the graph i.e., a subgraph that is a tree, contains all the vertices, and the sum of its weights is the least possible. Data Structures Inverted index - An Inverted Index is a data structure used to create full-text search. Given a set of text files, implement a program to create an inverted index. Also, create a user interface to do a search using that inverted index which returns a list of files that contain the query term/terms. The search index can be in memory. Text Fizz Buzz - Write a program that prints the numbers from 1 to 100. But for multiples of three print “Fizz” instead of the number and for the multiples of five print “Buzz”. For numbers which are multiples of both three and five print “FizzBuzz”. Reverse a String - Enter a string and the program will reverse it and print it out. Pig Latin - Pig Latin is a game of alterations played in the English language game. To create the Pig Latin form of an English word the initial consonant sound is transposed to the end of the word and an ay is affixed (Ex.: "banana" would yield anana-bay). Read Wikipedia for more information on rules. Count Vowels - Enter a string and the program counts the number of vowels in the text. For added complexity have it report a sum of each vowel found. Check if Palindrome - Checks if the string entered by the user is a palindrome. That is that it reads the same forwards as backward like “racecar” Count Words in a String - Counts the number of individual words in a string. For added complexity read these strings in from a text file and generate a summary. Text Editor - Notepad-style application that can open, edit, and save text documents. Optional: Add syntax highlighting and other features. RSS Feed Creator - Given a link to RSS/Atom Feed, get all posts and display them. Quote Tracker (market symbols etc) - A program that can go out and check the current value of stocks for a list of symbols entered by the user. The user can set how often the stocks are checked. For CLI, show whether the stock has moved up or down. Optional: If GUI, the program can show green up and red down arrows to show which direction the stock value has moved. Guestbook / Journal - A simple application that allows people to add comments or write journal entries. It can allow comments or not and timestamps for all entries. Could also be made into a shoutbox. Optional: Deploy it on Google App Engine or Heroku or any other PaaS (if possible, of course). Vigenere / Vernam / Ceasar Ciphers - Functions for encrypting and decrypting data messages. Then send them to a friend. Regex Query Tool - A tool that allows the user to enter a text string and then in a separate control enter a regex pattern. It will run the regular expression against the source text and return any matches or flag errors in the regular expression. Networking FTP Program - A file transfer program that can transfer files back and forth from a remote web sever. Bandwidth Monitor - A small utility program that tracks how much data you have uploaded and downloaded from the net during the course of your current online session. See if you can find out what periods of the day you use more and less and generate a report or graph that shows it. Port Scanner - Enter an IP address and a port range where the program will then attempt to find open ports on the given computer by connecting to each of them. On any successful connections mark the port as open. Mail Checker (POP3 / IMAP) - The user enters various account information include web server and IP, protocol type (POP3 or IMAP), and the application will check for email at a given interval. Country from IP Lookup - Enter an IP address and find the country that IP is registered in. Optional: Find the Ip automatically. Whois Search Tool - Enter an IP or host address and have it look it up through whois and return the results to you. Site Checker with Time Scheduling - An application that attempts to connect to a website or server every so many minute or a given time and check if it is up. If it is down, it will notify you by email or by posting a notice on the screen. Classes Product Inventory Project - Create an application that manages an inventory of products. Create a product class that has a price, id, and quantity on hand. Then create an inventory class that keeps track of various products and can sum up the inventory value. Airline / Hotel Reservation System - Create a reservation system that books airline seats or hotel rooms. It charges various rates for particular sections of the plane or hotel. For example, first class is going to cost more than a coach. Hotel rooms have penthouse suites which cost more. Keep track of when rooms will be available and can be scheduled. Company Manager - Create a hierarchy of classes - abstract class Employee and subclasses HourlyEmployee, SalariedEmployee, Manager, and Executive. Everyone's pay is calculated differently, research a bit about it. After you've established an employee hierarchy, create a Company class that allows you to manage the employees. You should be able to hire, fire, and raise employees. Bank Account Manager - Create a class called Account which will be an abstract class for three other classes called CheckingAccount, SavingsAccount, and BusinessAccount. Manage credits and debits from these accounts through an ATM-style program. Patient / Doctor Scheduler - Create a patient class and a doctor class. Have a doctor that can handle multiple patients and set up a scheduling program where a doctor can only handle 16 patients during an 8 hr workday. Recipe Creator and Manager - Create a recipe class with ingredients and put them in a recipe manager program that organizes them into categories like desserts, main courses, or by ingredients like chicken, beef, soups, pies, etc. Image Gallery - Create an image abstract class and then a class that inherits from it for each image type. Put them in a program that displays them in a gallery-style format for viewing. Shape Area and Perimeter Classes - Create an abstract class called Shape and then inherit from it other shapes like diamond, rectangle, circle, triangle, etc. Then have each class override the area and perimeter functionality to handle each shape type. Flower Shop Ordering To Go - Create a flower shop application that deals in flower objects and use those flower objects in a bouquet object which can then be sold. Keep track of the number of objects and when you may need to order more. Family Tree Creator - Create a class called Person which will have a name, when they were born, and when (and if) they died. Allow the user to create these Person classes and put them into a family tree structure. Print out the tree to the screen. Threading Create A Progress Bar for Downloads - Create a progress bar for applications that can keep track of a download in progress. The progress bar will be on a separate thread and will communicate with the main thread using delegates. Bulk Thumbnail Creator - Picture processing can take a bit of time for some transformations. Especially if the image is large. Create an image program that can take hundreds of images and converts them to a specified size in the background thread while you do other things. For added complexity, have one thread handling re-sizing, have another bulk renaming of thumbnails, etc. Web Page Scraper - Create an application that connects to a site and pulls out all links, or images, and saves them to a list. Optional: Organize the indexed content and don’t allow duplicates. Have it put the results into an easily searchable index file. Online White Board - Create an application that allows you to draw pictures, write notes and use various colors to flesh out ideas for projects. Optional: Add a feature to invite friends to collaborate on a whiteboard online. Get Atomic Time from Internet Clock - This program will get the true atomic time from an atomic time clock on the Internet. Use any one of the atomic clocks returned by a simple Google search. Fetch Current Weather - Get the current weather for a given zip/postal code. Optional: Try locating the user automatically. Scheduled Auto Login and Action - Make an application that logs into a given site on a schedule and invokes a certain action and then logs out. This can be useful for checking webmail, posting regular content, or getting info for other applications and saving it to your computer. E-Card Generator - Make a site that allows people to generate their own little e-cards and send them to other people. Do not use Flash. Use a picture library and perhaps insightful mottos or quotes. Content Management System - Create a content management system (CMS) like Joomla, Drupal, PHP Nuke, etc. Start small. Optional: Allow for the addition of modules/addons. Web Board (Forum) - Create a forum for you and your buddies to post, administer and share thoughts and ideas. CAPTCHA Maker - Ever see those images with letters numbers when you signup for a service and then ask you to enter what you see? It keeps web bots from automatically signing up and spamming. Try creating one yourself for online forms. Files Quiz Maker - Make an application that takes various questions from a file, picked randomly, and puts together a quiz for students. Each quiz can be different and then reads a key to grade the quizzes. Sort Excel/CSV File Utility - Reads a file of records, sorts them, and then writes them back to the file. Allow the user to choose various sort style and sorting based on a particular field. Create Zip File Maker - The user enters various files from different directories and the program zips them up into a zip file. Optional: Apply actual compression to the files. Start with Huffman Algorithm. PDF Generator - An application that can read in a text file, HTML file, or some other file and generates a PDF file out of it. Great for a web-based service where the user uploads the file and the program returns a PDF of the file. Optional: Deploy on GAE or Heroku if possible. Mp3 Tagger - Modify and add ID3v1 tags to MP3 files. See if you can also add in the album art into the MP3 file’s header as well as other ID3v2 tags. Code Snippet Manager - Another utility program that allows coders to put in functions, classes, or other tidbits to save for use later. Organized by the type of snippet or language the coder can quickly lookup code. Optional: For extra practice try adding syntax highlighting based on the language. Databases SQL Query Analyzer - A utility application in which a user can enter a query and have it run against a local database and look for ways to make it more efficient. Remote SQL Tool - A utility that can execute queries on remote servers from your local computer across the Internet. It should take in a remote host, user name, and password, run the query and return the results. Report Generator - Create a utility that generates a report based on some tables in a database. Generates sales reports based on the order/order details tables or sums up the day's current database activity. Event Scheduler and Calendar - Make an application that allows the user to enter a date and time of an event, event notes, and then schedule those events on a calendar. The user can then browse the calendar or search the calendar for specific events. Optional: Allow the application to create re-occurrence events that reoccur every day, week, month, year, etc. Budget Tracker - Write an application that keeps track of a household’s budget. The user can add expenses, income, and recurring costs to find out how much they are saving or losing over a period of time. Optional: Allow the user to specify a date range and see the net flow of money in and out of the house budget for that time period. TV Show Tracker - Got a favorite show you don’t want to miss? Don’t have a PVR or want to be able to find the show to then PVR it later? Make an application that can search various online TV Guide sites, locate the shows/times/channels and add them to a database application. The database/website then can send you email reminders that a show is about to start and which channel it will be on. Travel Planner System - Make a system that allows users to put together their own little travel itinerary and keep track of the airline/hotel arrangements, points of interest, budget, and schedule. Graphics and Multimedia Slide Show - Make an application that shows various pictures in a slide show format. Optional: Try adding various effects like fade in/out, star wipe, and window blinds transitions. Stream Video from Online - Try to create your own online streaming video player. Mp3 Player - A simple program for playing your favorite music files. Add features you think are missing from your favorite music player. Watermarking Application - Have some pictures you want copyright protected? Add your own logo or text lightly across the background so that no one can simply steal your graphics off your site. Make a program that will add this watermark to the picture. Optional: Use threading to process multiple images simultaneously. Turtle Graphics - This is a common project where you create a floor of 20 x 20 squares. Using various commands you tell a turtle to draw a line on the floor. You have moved forward, left or right, lift or drop the pen, etc. Do a search online for "Turtle Graphics" for more information. Optional: Allow the program to read in the list of commands from a file. GIF Creator A program that puts together multiple images (PNGs, JPGs, TIFFs) to make a smooth GIF that can be exported. Optional: Make the program convert small video files to GIFs as well. Security Caesar cipher - Implement a Caesar cipher, both encoding, and decoding. The key is an integer from 1 to 25. This cipher rotates the letters of the alphabet (A to Z). The encoding replaces each letter with the 1st to 25th next letter in the alphabet (wrapping Z to A). So key 2 encrypts "HI" to "JK", but key 20 encrypts "HI" to "BC". This simple "monoalphabetic substitution cipher" provides almost no security, because an attacker who has the encoded message can either use frequency analysis to guess the key, or just try all 25 keys.
Sfedfcv / Redesigned PancakeSkip to content github / docs Code Issues 80 Pull requests 35 Discussions Actions Projects 2 Security Insights Merge branch 'main' into 1862-Add-Travis-CI-migration-table 1862-Add-Travis-CI-migration-table (#1869, Iixixi/ZachryTylerWood#102, THEBOLCK79/docs#1, sbnbhk/docs#1) @martin389 martin389 committed on Dec 9, 2020 2 parents 2f9ec0c + 1588f50 commit 1a56ed136914e522f3a23ecc2be1c49f479a1a6a Showing 501 changed files with 5,397 additions and 1,362 deletions. 2 .github/allowed-actions.js @@ -30,7 +30,7 @@ module.exports = [ 'rachmari/labeler@832d42ec5523f3c6d46e8168de71cd54363e3e2e', 'repo-sync/github-sync@3832fe8e2be32372e1b3970bbae8e7079edeec88', 'repo-sync/pull-request@33777245b1aace1a58c87a29c90321aa7a74bd7d', 'rtCamp/action-slack-notify@e17352feaf9aee300bf0ebc1dfbf467d80438815', 'someimportantcompany/github-actions-slack-message@0b470c14b39da4260ed9e3f9a4f1298a74ccdefd', 'tjenkinson/gh-action-auto-merge-dependency-updates@cee2ac0', 'EndBug/add-and-commit@9358097a71ad9fb9e2f9624c6098c89193d83575' ] 72 .github/workflows/confirm-internal-staff-work-in-docs.yml @@ -0,0 +1,72 @@ name: Confirm internal staff meant to post in public on: issues: types: - opened - reopened - transferred pull_request_target: types: - opened - reopened jobs: check-team-membership: runs-on: ubuntu-latest continue-on-error: true if: github.repository == 'github/docs' steps: - uses: actions/github-script@626af12fe9a53dc2972b48385e7fe7dec79145c9 with: github-token: ${{ secrets.DOCUBOT_FR_PROJECT_BOARD_WORKFLOWS_REPO_ORG_READ_SCOPES }} script: | // Only perform this action with GitHub employees try { await github.teams.getMembershipForUserInOrg({ org: 'github', team_slug: 'employees', username: context.payload.sender.login, }); } catch(err) { // An error will be thrown if the user is not a GitHub employee // If a user is not a GitHub employee, we should stop here and // Not send a notification return } // Don't perform this action with Docs team members try { await github.teams.getMembershipForUserInOrg({ org: 'github', team_slug: 'docs', username: context.payload.sender.login, }); // If the user is a Docs team member, we should stop here and not send // a notification return } catch(err) { // An error will be thrown if the user is not a Docs team member // If a user is not a Docs team member we should continue and send // the notification } const issueNo = context.number || context.issue.number // Create an issue in our private repo await github.issues.create({ owner: 'github', repo: 'docs-internal', title: `@${context.payload.sender.login} confirm that \#${issueNo} should be in the public github/docs repo`, body: `@${context.payload.sender.login} opened https://github.com/github/docs/issues/${issueNo} publicly in the github/docs repo, instead of the private github/docs-internal repo.\n\n@${context.payload.sender.login}, please confirm that this belongs in the public repo and that no sensitive information was disclosed by commenting below and closing the issue.\n\nIf this was not intentional and sensitive information was shared, please delete https://github.com/github/docs/issues/${issueNo} and notify us in the \#docs-open-source channel.\n\nThanks! \n\n/cc @github/docs @github/docs-engineering` }); throw new Error('A Hubber opened an issue on the public github/docs repo'); - name: Send Slack notification if a GitHub employee who isn't on the docs team opens an issue in public if: ${{ failure() && github.repository == 'github/docs' }} uses: someimportantcompany/github-actions-slack-message@0b470c14b39da4260ed9e3f9a4f1298a74ccdefd with: channel: ${{ secrets.DOCS_OPEN_SOURCE_SLACK_CHANNEL_ID }} bot-token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }} text: <@${{github.actor}}> opened https://github.com/github/docs/issues/${{ github.event.number || github.event.issue.number }} publicly on the github/docs repo instead of the private github/docs-internal repo. They have been notified via a new issue in the github/docs-internal repo to confirm this was intentional. 15 .github/workflows/js-lint.yml @@ -10,23 +10,8 @@ on: - translations jobs: see_if_should_skip: runs-on: ubuntu-latest outputs: should_skip: ${{ steps.skip_check.outputs.should_skip }} steps: - id: skip_check uses: fkirc/skip-duplicate-actions@36feb0d8d062137530c2e00bd278d138fe191289 with: cancel_others: 'false' github_token: ${{ github.token }} paths: '["**/*.js", "package*.json", ".github/workflows/js-lint.yml", ".eslint*"]' lint: runs-on: ubuntu-latest needs: see_if_should_skip if: ${{ needs.see_if_should_skip.outputs.should_skip != 'true' }} steps: - name: Check out repo uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f 13 .github/workflows/repo-freeze-reminders.yml @@ -14,11 +14,10 @@ jobs: if: github.repository == 'github/docs-internal' steps: - name: Send Slack notification if repo is frozen uses: someimportantcompany/github-actions-slack-message@0b470c14b39da4260ed9e3f9a4f1298a74ccdefd if: ${{ env.FREEZE == 'true' }} uses: rtCamp/action-slack-notify@e17352feaf9aee300bf0ebc1dfbf467d80438815 env: SLACK_WEBHOOK: ${{ secrets.DOCS_ALERTS_SLACK_WEBHOOK }} SLACK_USERNAME: docs-repo-sync SLACK_ICON_EMOJI: ':freezing_face:' SLACK_COLOR: '#51A0D5' # Carolina Blue SLACK_MESSAGE: All repo-sync runs will fail for ${{ github.repository }} because the repo is currently frozen! with: channel: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }} bot-token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }} color: info text: All repo-sync runs will fail for ${{ github.repository }} because the repo is currently frozen! 54 .github/workflows/repo-sync-stalls.yml @@ -0,0 +1,54 @@ name: Repo Sync Stalls on: workflow_dispatch: schedule: - cron: '*/30 * * * *' jobs: check-freezer: name: Check for deployment freezes runs-on: ubuntu-latest steps: - name: Exit if repo is frozen if: ${{ env.FREEZE == 'true' }} run: | echo 'The repo is currently frozen! Exiting this workflow.' exit 1 # prevents further steps from running repo-sync-stalls: runs-on: ubuntu-latest steps: - name: Check if repo sync is stalled uses: actions/github-script@626af12fe9a53dc2972b48385e7fe7dec79145c9 with: github-token: ${{ secrets.DOCUBOT_FR_PROJECT_BOARD_WORKFLOWS_REPO_ORG_READ_SCOPES }} script: | let pulls; const owner = context.repo.owner const repo = context.repo.repo try { pulls = await github.pulls.list({ owner: owner, repo: repo, head: `${owner}:repo-sync`, state: 'open' }); } catch(err) { throw err return } pulls.data.forEach(pr => { const timeDelta = Date.now() - Date.parse(pr.created_at); const minutesOpen = timeDelta / 1000 / 60; if (minutesOpen > 30) { core.setFailed('Repo sync appears to be stalled') } }) - name: Send Slack notification if workflow fails uses: someimportantcompany/github-actions-slack-message@0b470c14b39da4260ed9e3f9a4f1298a74ccdefd if: failure() with: channel: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }} bot-token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }} color: failure text: Repo sync appears to be stalled for ${{github.repository}}. See https://github.com/${{github.repository}}/pulls?q=is%3Apr+is%3Aopen+repo+sync 16 .github/workflows/repo-sync.yml @@ -7,6 +7,7 @@ name: Repo Sync on: workflow_dispatch: schedule: - cron: '*/15 * * * *' # every 15 minutes @@ -70,11 +71,10 @@ jobs: number: ${{ steps.find-pull-request.outputs.number }} - name: Send Slack notification if workflow fails uses: rtCamp/action-slack-notify@e17352feaf9aee300bf0ebc1dfbf467d80438815 if: ${{ failure() }} env: SLACK_WEBHOOK: ${{ secrets.DOCS_ALERTS_SLACK_WEBHOOK }} SLACK_USERNAME: docs-repo-sync SLACK_ICON_EMOJI: ':ohno:' SLACK_COLOR: '#B90E0A' # Crimson SLACK_MESSAGE: The last repo-sync run for ${{github.repository}} failed. See https://github.com/${{github.repository}}/actions?query=workflow%3A%22Repo+Sync%22 uses: someimportantcompany/github-actions-slack-message@0b470c14b39da4260ed9e3f9a4f1298a74ccdefd if: failure() with: channel: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }} bot-token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }} color: failure text: The last repo-sync run for ${{github.repository}} failed. See https://github.com/${{github.repository}}/actions?query=workflow%3A%22Repo+Sync%22 10 .github/workflows/sync-algolia-search-indices.yml @@ -33,8 +33,10 @@ jobs: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: npm run sync-search - name: Send slack notification if workflow run fails uses: rtCamp/action-slack-notify@e17352feaf9aee300bf0ebc1dfbf467d80438815 uses: someimportantcompany/github-actions-slack-message@0b470c14b39da4260ed9e3f9a4f1298a74ccdefd if: failure() env: SLACK_WEBHOOK: ${{ secrets.DOCS_ALERTS_SLACK_WEBHOOK }} SLACK_MESSAGE: The last Algolia workflow run for ${{github.repository}} failed. Search actions for `workflow:Algolia` with: channel: ${{ secrets.DOCS_ALERTS_SLACK_CHANNEL_ID }} bot-token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }} color: failure text: The last Algolia workflow run for ${{github.repository}} failed. Search actions for `workflow:Algolia` 15 .github/workflows/yml-lint.yml @@ -10,23 +10,8 @@ on: - translations jobs: see_if_should_skip: runs-on: ubuntu-latest outputs: should_skip: ${{ steps.skip_check.outputs.should_skip }} steps: - id: skip_check uses: fkirc/skip-duplicate-actions@36feb0d8d062137530c2e00bd278d138fe191289 with: cancel_others: 'false' github_token: ${{ github.token }} paths: '["**/*.yml", "**/*.yaml", "package*.json", ".github/workflows/yml-lint.yml"]' lint: runs-on: ubuntu-latest needs: see_if_should_skip if: ${{ needs.see_if_should_skip.outputs.should_skip != 'true' }} steps: - name: Check out repo uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f 4 README.md @@ -28,7 +28,7 @@ If you've found a problem, you can open an issue using a [template](https://gith #### Solve an issue If you have a solution to one of the open issues, you will need to fork the repository and submit a PR using the [template](https://github.com/github/docs/blob/main/CONTRIBUTING.md#pull-request-template) that is visible automatically in the pull request body. For more details about this process, please check out [Getting Started with Contributing](/CONTRIBUTING.md). If you have a solution to one of the open issues, you will need to fork the repository and submit a pull request using the [template](https://github.com/github/docs/blob/main/CONTRIBUTING.md#pull-request-template) that is visible automatically in the pull request body. For more details about this process, please check out [Getting Started with Contributing](/CONTRIBUTING.md). #### Join us in discussions @@ -50,6 +50,8 @@ There are a few more things to know when you're getting started with this repo: In addition to the README you're reading right now, this repo includes other READMEs that describe the purpose of each subdirectory in more detail: - [content/README.md](content/README.md) - [content/graphql/README.md](content/graphql/README.md) - [content/rest/README.md](content/rest/README.md) - [contributing/README.md](contributing/README.md) - [data/README.md](data/README.md) - [data/reusables/README.md](data/reusables/README.md) BIN +164 KB assets/images/help/classroom/assignment-group-hero.png Binary file not shown. BIN +75.5 KB assets/images/help/classroom/assignment-ide-go-grant-access-button.png Binary file not shown. BIN +175 KB assets/images/help/classroom/assignment-individual-hero.png Binary file not shown. BIN +27.6 KB assets/images/help/classroom/assignment-repository-ide-button-in-readme.png Binary file not shown. BIN +83.4 KB assets/images/help/classroom/assignments-assign-deadline.png Binary file not shown. BIN +32.4 KB assets/images/help/classroom/assignments-assignment-title.png Binary file not shown. BIN +27.7 KB assets/images/help/classroom/assignments-autograding-click-pencil-or-trash.png Binary file not shown. BIN +72 KB assets/images/help/classroom/assignments-choose-repository-visibility.png Binary file not shown. BIN +20.1 KB assets/images/help/classroom/assignments-click-continue-button.png Binary file not shown. BIN +23.7 KB assets/images/help/classroom/assignments-click-create-assignment-button.png Binary file not shown. BIN +76.4 KB assets/images/help/classroom/assignments-click-grading-and-feedback.png Binary file not shown. BIN +53.1 KB assets/images/help/classroom/assignments-click-new-assignment-button.png Binary file not shown. BIN +134 KB assets/images/help/classroom/assignments-click-online-ide.png Binary file not shown. BIN +77.8 KB assets/images/help/classroom/assignments-click-pencil.png Binary file not shown. BIN +18.8 KB assets/images/help/classroom/assignments-click-review-button.png Binary file not shown. BIN +20.6 KB assets/images/help/classroom/assignments-click-save-test-case-button.png Binary file not shown. BIN +121 KB assets/images/help/classroom/assignments-click-template-repository-in-list.png Binary file not shown. BIN +21.1 KB assets/images/help/classroom/assignments-click-update-assignment.png Binary file not shown. BIN +76.9 KB assets/images/help/classroom/assignments-click-view-ide.png Binary file not shown. BIN +96.5 KB assets/images/help/classroom/assignments-click-view-test.png Binary file not shown. BIN +71.3 KB assets/images/help/classroom/assignments-define-teams.png Binary file not shown. BIN +39.4 KB assets/images/help/classroom/assignments-enable-feedback-pull-requests.png Binary file not shown. BIN +40.4 KB assets/images/help/classroom/assignments-type-protected-file-paths.png Binary file not shown. BIN +330 KB assets/images/help/classroom/autograding-actions-logs.png Binary file not shown. BIN +187 KB assets/images/help/classroom/autograding-actions-tab.png Binary file not shown. BIN +94.9 KB assets/images/help/classroom/autograding-click-grading-method.png Diff not rendered. BIN +57.5 KB assets/images/help/classroom/autograding-click-pencil.png Diff not rendered. BIN +57.7 KB assets/images/help/classroom/autograding-click-trash.png Diff not rendered. BIN +168 KB assets/images/help/classroom/autograding-hero.png Diff not rendered. BIN +154 KB assets/images/help/classroom/classroom-add-students-to-your-roster.png Diff not rendered. BIN +166 KB assets/images/help/classroom/classroom-copy-credentials.png Diff not rendered. BIN +181 KB assets/images/help/classroom/classroom-hero.png Diff not rendered. BIN +48.3 KB assets/images/help/classroom/classroom-settings-click-connection-settings.png Diff not rendered. BIN +94 KB ...ges/help/classroom/classroom-settings-click-disconnect-from-your-lms-button.png Diff not rendered. BIN +148 KB assets/images/help/classroom/classroom-settings-click-lms.png Diff not rendered. BIN +149 KB assets/images/help/classroom/click-assignment-in-list.png Diff not rendered. BIN +52.3 KB assets/images/help/classroom/click-classroom-in-list.png Diff not rendered. BIN +49.5 KB assets/images/help/classroom/click-create-classroom-button.png Diff not rendered. BIN +30 KB assets/images/help/classroom/click-create-roster-button.png Diff not rendered. BIN +78.2 KB assets/images/help/classroom/click-delete-classroom-button.png Diff not rendered. BIN +60.8 KB ...images/help/classroom/click-import-from-a-learning-management-system-button.png Diff not rendered. BIN +51.9 KB assets/images/help/classroom/click-new-classroom-button.png Diff not rendered. BIN +83.4 KB assets/images/help/classroom/click-organization.png Diff not rendered. BIN +28.4 KB assets/images/help/classroom/click-settings.png Diff not rendered. BIN +29.7 KB assets/images/help/classroom/click-students.png Diff not rendered. BIN +60 KB assets/images/help/classroom/click-update-students-button.png Diff not rendered. BIN +127 KB assets/images/help/classroom/delete-classroom-click-delete-classroom-button.png Diff not rendered. BIN +104 KB assets/images/help/classroom/delete-classroom-modal-with-warning.png Diff not rendered. BIN +264 KB assets/images/help/classroom/ide-makecode-arcade-version-control-button.png Diff not rendered. BIN +69.4 KB assets/images/help/classroom/ide-replit-version-control-button.png Diff not rendered. BIN +234 KB assets/images/help/classroom/lms-github-classroom-credentials.png Diff not rendered. BIN +955 KB assets/images/help/classroom/probot-settings.gif Diff not rendered. BIN +113 KB assets/images/help/classroom/roster-hero.png Diff not rendered. BIN +40.4 KB assets/images/help/classroom/settings-click-rename-classroom-button.png Diff not rendered. BIN +41 KB assets/images/help/classroom/settings-type-classroom-name.png Diff not rendered. BIN +140 KB assets/images/help/classroom/setup-click-authorize-github-classroom.png Diff not rendered. BIN +102 KB assets/images/help/classroom/setup-click-authorize-github.png Diff not rendered. BIN +163 KB assets/images/help/classroom/setup-click-grant.png Diff not rendered. BIN +324 KB assets/images/help/classroom/students-click-delete-roster-button-in-modal.png Diff not rendered. BIN +91.1 KB assets/images/help/classroom/students-click-delete-roster-button.png Diff not rendered. BIN +48.2 KB assets/images/help/classroom/type-classroom-name.png Diff not rendered. BIN +174 KB assets/images/help/classroom/type-or-upload-student-identifiers.png Diff not rendered. BIN +83.3 KB assets/images/help/classroom/use-drop-down-then-click-archive.png Diff not rendered. BIN +45.2 KB assets/images/help/classroom/use-drop-down-then-click-unarchive.png Diff not rendered. BIN +55.4 KB assets/images/help/discussions/choose-new-category.png Diff not rendered. BIN +56.8 KB assets/images/help/discussions/click-delete-and-move-button.png Diff not rendered. BIN +59.7 KB assets/images/help/discussions/click-delete-discussion.png Diff not rendered. BIN +65.3 KB assets/images/help/discussions/click-delete-for-category.png Diff not rendered. BIN +68.9 KB assets/images/help/discussions/click-delete-this-discussion-button.png Diff not rendered. BIN +353 KB assets/images/help/discussions/click-discussion-in-list.png Diff not rendered. BIN +41 KB assets/images/help/discussions/click-edit-categories.png Diff not rendered. BIN +64.3 KB assets/images/help/discussions/click-edit-for-category.png Diff not rendered. BIN +60.2 KB assets/images/help/discussions/click-edit-pinned-discussion.png Diff not rendered. BIN +104 KB assets/images/help/discussions/click-new-category-button.png Diff not rendered. BIN +98.2 KB assets/images/help/discussions/click-pin-discussion-button.png Diff not rendered. BIN +55.7 KB assets/images/help/discussions/click-pin-discussion.png Diff not rendered. BIN +104 KB assets/images/help/discussions/click-save.png Diff not rendered. BIN +59.9 KB assets/images/help/discussions/click-transfer-discussion-button.png Diff not rendered. BIN +60.2 KB assets/images/help/discussions/click-transfer-discussion.png Diff not rendered. BIN +63.3 KB assets/images/help/discussions/click-unpin-discussion-button.png Diff not rendered. BIN +59.8 KB assets/images/help/discussions/click-unpin-discussion.png Diff not rendered. BIN +140 KB assets/images/help/discussions/comment-mark-as-answer-button.png Diff not rendered. BIN +136 KB assets/images/help/discussions/comment-marked-as-answer.png Diff not rendered. BIN +234 KB assets/images/help/discussions/customize-pinned-discussion.png Diff not rendered. BIN +1.21 MB assets/images/help/discussions/discussons-hero.png Diff not rendered. BIN +139 KB assets/images/help/discussions/edit-category-details.png Diff not rendered. BIN +136 KB assets/images/help/discussions/edit-existing-category-details.png Diff not rendered. BIN +55.5 KB assets/images/help/discussions/existing-category-click-save-changes-button.png Diff not rendered. BIN +680 KB assets/images/help/discussions/hero.png Diff not rendered. BIN +307 KB assets/images/help/discussions/most-helpful.png Diff not rendered. BIN +52.9 KB assets/images/help/discussions/new-category-click-create-button.png Diff not rendered. BIN +132 KB assets/images/help/discussions/new-discussion-button.png Diff not rendered. BIN +140 KB assets/images/help/discussions/new-discussion-select-category-dropdown-menu.png Diff not rendered. BIN +46.7 KB assets/images/help/discussions/new-discussion-start-discussion-button.png Diff not rendered. BIN +108 KB assets/images/help/discussions/new-discussion-title-and-body-fields.png Diff not rendered. BIN +23.1 KB assets/images/help/discussions/public-repo-settings.png Diff not rendered. BIN +49.5 KB assets/images/help/discussions/repository-discussions-tab.png Diff not rendered. BIN +51.8 KB assets/images/help/discussions/search-and-filter-controls.png Diff not rendered. BIN +44.4 KB assets/images/help/discussions/search-result.png Diff not rendered. BIN +35.4 KB assets/images/help/discussions/select-discussions-checkbox.png Diff not rendered. BIN +44.8 KB assets/images/help/discussions/setup-discussions-button.png Diff not rendered. BIN +95.9 KB assets/images/help/discussions/toggle-allow-users-with-read-access-checkbox.png Diff not rendered. BIN +73 KB assets/images/help/discussions/unanswered-discussion.png Diff not rendered. BIN +81.3 KB assets/images/help/discussions/use-choose-a-repository-drop-down.png Diff not rendered. BIN +30.3 KB assets/images/help/discussions/your-discussions.png Diff not rendered. BIN +563 KB assets/images/help/education/click-get-teacher-benefits.png Diff not rendered. BIN +116 KB assets/images/help/images/overview-actions-result-navigate.png Diff not rendered. BIN +150 KB assets/images/help/images/overview-actions-result-updated-2.png Diff not rendered. BIN +128 KB assets/images/help/images/workflow-graph-job.png Diff not rendered. BIN +135 KB assets/images/help/images/workflow-graph.png Diff not rendered. BIN +5.46 KB assets/images/help/organizations/update-profile-button.png Diff not rendered. BIN +44.6 KB assets/images/help/pull_requests/dependency-review-rich-diff.png Diff not rendered. BIN +24.6 KB assets/images/help/pull_requests/dependency-review-source-diff.png Diff not rendered. BIN +214 KB assets/images/help/pull_requests/dependency-review-vulnerability.png Diff not rendered. BIN +105 KB assets/images/help/pull_requests/file-filter-menu-json.png Diff not rendered. BIN +22.5 KB (510%) assets/images/help/pull_requests/pull-request-tabs-changed-files.png Diff not rendered. BIN +45.2 KB assets/images/help/repository/actions-delete-artifact-updated.png Diff not rendered. BIN +122 KB assets/images/help/repository/actions-failed-pester-test-updated.png Diff not rendered. BIN +45.4 KB assets/images/help/repository/artifact-drop-down-updated.png Diff not rendered. BIN +54.5 KB assets/images/help/repository/cancel-check-suite-updated.png Diff not rendered. BIN +120 KB assets/images/help/repository/copy-link-button-updated-2.png Diff not rendered. BIN +77.6 KB assets/images/help/repository/delete-all-logs-updated-2.png Diff not rendered. BIN +326 KB assets/images/help/repository/docker-action-workflow-run-updated.png Diff not rendered. BIN +84.6 KB assets/images/help/repository/download-logs-drop-down-updated-2.png Diff not rendered. BIN +170 KB assets/images/help/repository/in-progress-run.png Diff not rendered. BIN +124 KB assets/images/help/repository/javascript-action-workflow-run-updated-2.png Diff not rendered. BIN +116 KB assets/images/help/repository/passing-data-between-jobs-in-a-workflow-updated.png Diff not rendered. BIN +80.8 KB assets/images/help/repository/rerun-checks-drop-down-updated.png Diff not rendered. BIN +41.2 KB assets/images/help/repository/search-log-box-updated-2.png Diff not rendered. BIN +133 KB assets/images/help/repository/super-linter-workflow-results-updated-2.png Diff not rendered. BIN +97.5 KB assets/images/help/repository/superlinter-lint-code-base-job-updated.png Diff not rendered. BIN -128 KB assets/images/help/repository/upload-build-test-artifact.png Diff not rendered. BIN +27.5 KB (170%) assets/images/help/repository/view-run-billable-time.png Diff not rendered. BIN +54.8 KB assets/images/help/repository/workflow-run-kebab-horizontal-icon-updated-2.png Diff not rendered. BIN +7.54 KB assets/images/help/settings/appearance-tab.png Diff not rendered. BIN +39.7 KB assets/images/help/settings/theme-settings-radio-buttons.png Diff not rendered. BIN +11.1 KB assets/images/help/settings/update-theme-preference-button.png Diff not rendered. BIN +22.5 KB assets/images/help/sponsors/billing-account-switcher.png Diff not rendered. BIN +6.37 KB (150%) assets/images/help/sponsors/edit-sponsorship-payment-button.png Diff not rendered. BIN +34.8 KB assets/images/help/sponsors/link-account-button.png Diff not rendered. BIN +12.8 KB (170%) assets/images/help/sponsors/manage-your-sponsorship-button.png Diff not rendered. BIN +20.6 KB assets/images/help/sponsors/organization-update-email-textbox.png Diff not rendered. BIN +13.5 KB assets/images/help/sponsors/pay-prorated-amount-link.png Diff not rendered. BIN +34.7 KB assets/images/help/sponsors/select-an-account-drop-down.png Diff not rendered. BIN +17 KB assets/images/help/sponsors/sponsor-as-drop-down-menu.png Diff not rendered. BIN +15.8 KB assets/images/help/sponsors/sponsoring-as-drop-down-menu.png Diff not rendered. BIN +16.1 KB assets/images/help/sponsors/sponsoring-settings-button.png Diff not rendered. BIN +29.5 KB assets/images/help/sponsors/sponsoring-tab.png Diff not rendered. BIN +7.91 KB assets/images/help/sponsors/update-checkbox-manage.png Diff not rendered. BIN +43 KB (160%) assets/images/marketplace/marketplace-request-button.png Diff not rendered. BIN +53.6 KB assets/images/marketplace/marketplace_verified_creator_badges_apps.png Diff not rendered. 6 content/actions/creating-actions/creating-a-docker-container-action.md @@ -226,6 +226,10 @@ jobs: ``` {% endraw %} From your repository, click the **Actions** tab, and select the latest workflow run. You should see "Hello Mona the Octocat" or the name you used for the `who-to-greet` input and the timestamp printed in the log. From your repository, click the **Actions** tab, and select the latest workflow run. {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}Under **Jobs** or in the visualization graph, click **A job to say hello**. {% endif %}You should see "Hello Mona the Octocat" or the name you used for the `who-to-greet` input and the timestamp printed in the log. {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}  {% else %}  {% endif %} 6 content/actions/creating-actions/creating-a-javascript-action.md @@ -261,9 +261,11 @@ jobs: ``` {% endraw %} From your repository, click the **Actions** tab, and select the latest workflow run. You should see "Hello Mona the Octocat" or the name you used for the `who-to-greet` input and the timestamp printed in the log. From your repository, click the **Actions** tab, and select the latest workflow run. {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}Under **Jobs** or in the visualization graph, click **A job to say hello**. {% endif %}You should see "Hello Mona the Octocat" or the name you used for the `who-to-greet` input and the timestamp printed in the log. {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}  {% elsif currentVersion ver_gt "enterprise-server@2.22" %}  {% else %}  4 content/actions/guides/about-packaging-with-github-actions.md @@ -25,7 +25,11 @@ Creating a package at the end of a continuous integration workflow can help duri Now, when reviewing a pull request, you'll be able to look at the workflow run and download the artifact that was produced. {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}  {% else %}  {% endif %} This will let you run the code in the pull request on your machine, which can help with debugging or testing the pull request. 4 content/actions/guides/building-and-testing-powershell.md @@ -60,7 +60,11 @@ jobs: * `run: Test-Path resultsfile.log` - Check whether a file called `resultsfile.log` is present in the repository's root directory. * `Should -Be $true` - Uses Pester to define an expected result. If the result is unexpected, then {% data variables.product.prodname_actions %} flags this as a failed test. For example: {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}  {% else %}  {% endif %} * `Invoke-Pester Unit.Tests.ps1 -Passthru` - Uses Pester to execute tests defined in a file called `Unit.Tests.ps1`. For example, to perform the same test described above, the `Unit.Tests.ps1` will contain the following: ``` 7 content/actions/guides/storing-workflow-data-as-artifacts.md @@ -108,8 +108,6 @@ jobs: path: output/test/code-coverage.html ```  {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} ### Configuring a custom artifact retention period @@ -238,7 +236,12 @@ jobs: echo The result is $value ``` The workflow run will archive any artifacts that it generated. For more information on downloading archived artifacts, see "[Downloading workflow artifacts](/actions/managing-workflow-runs/downloading-workflow-artifacts)." {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}  {% else %}  {% endif %} {% if currentVersion == "free-pro-team@latest" %} 8 content/actions/index.md @@ -68,18 +68,18 @@ versions: <h2 class="mb-2 font-mktg h1">Code examples</h2> <div class="pr-lg-3 mb-5 mt-3"> <input class="js-code-example-filter input-lg py-2 px-3 col-12 col-lg-8 form-control" placeholder="Search code examples" type="search" autocomplete="off" aria-label="Search code examples"/> <input class="js-filter-card-filter input-lg py-2 px-3 col-12 col-lg-8 form-control" placeholder="Search code examples" type="search" autocomplete="off" aria-label="Search code examples"/> </div> <div class="d-flex flex-wrap gutter"> {% render 'code-example-card' for actionsCodeExamples as example %} </div> <button class="js-code-example-show-more btn btn-outline float-right">Show more {% octicon "arrow-right" %}</button> <button class="js-filter-card-show-more btn btn-outline float-right">Show more {% octicon "arrow-right" %}</button> <div class="js-code-example-no-results d-none py-4 text-center text-gray font-mktg"> <div class="js-filter-card-no-results d-none py-4 text-center text-gray font-mktg"> <div class="mb-3">{% octicon "search" width="24" %}</div> <h3 class="text-normal">Sorry, there is no result for <strong class="js-code-example-filter-value"></strong></h3> <h3 class="text-normal">Sorry, there is no result for <strong class="js-filter-card-value"></strong></h3> <p class="my-3 f4">It looks like we don't have an example that fits your filter.<br>Try another filter or add your code example</p> <a href="https://github.com/github/docs/blob/main/data/variables/action_code_examples.yml">Learn how to add a code example {% octicon "arrow-right" %}</a> </div> 11 content/actions/learn-github-actions/introduction-to-github-actions.md @@ -204,7 +204,7 @@ In this diagram, you can see the workflow file you just created and how the {% d ### Viewing the job's activity Once your job has started running, you can view each step's activity on {% data variables.product.prodname_dotcom %}. Once your job has started running, you can {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}see a visualization graph of the run's progress and {% endif %}view each step's activity on {% data variables.product.prodname_dotcom %}. {% data reusables.repositories.navigate-to-repo %} 1. Under your repository name, click **Actions**. @@ -213,7 +213,14 @@ Once your job has started running, you can view each step's activity on {% data  1. Under "Workflow runs", click the name of the run you want to see.  {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} 1. Under **Jobs** or in the visualization graph, click the job you want to see.  {% endif %} {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} 1. View the results of each step.  {% elsif currentVersion ver_gt "enterprise-server@2.22" %} 1. Click on the job name to see the results of each step.  {% else %} 7 content/actions/managing-workflow-runs/canceling-a-workflow.md @@ -17,9 +17,14 @@ versions: {% data reusables.repositories.navigate-to-repo %} {% data reusables.repositories.actions-tab %} {% data reusables.repositories.navigate-to-workflow %} {% data reusables.repositories.view-run %} 1. From the list of workflow runs, click the name of the `queued` or `in progress` run that you want to cancel.  1. In the upper-right corner of the workflow, click **Cancel workflow**. {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}  {% else %}  {% endif %} ### Steps {% data variables.product.prodname_dotcom %} takes to cancel a workflow run 4 content/actions/managing-workflow-runs/downloading-workflow-artifacts.md @@ -20,4 +20,8 @@ versions: {% data reusables.repositories.navigate-to-workflow %} {% data reusables.repositories.view-run %} 1. Under **Artifacts**, click the artifact you want to download. {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}  {% else %}  {% endif %} 1 content/actions/managing-workflow-runs/index.md @@ -18,6 +18,7 @@ versions: {% data reusables.actions.enterprise-beta %} {% data reusables.actions.enterprise-github-hosted-runners %} {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}{% link_in_list /using-the-visualization-graph %}{% endif %} {% link_in_list /viewing-workflow-run-history %} {% link_in_list /using-workflow-run-logs %} {% link_in_list /manually-running-a-workflow %} 3 content/actions/managing-workflow-runs/re-running-a-workflow.md @@ -16,5 +16,4 @@ versions: {% data reusables.repositories.actions-tab %} {% data reusables.repositories.navigate-to-workflow %} {% data reusables.repositories.view-run %} 1. In the upper-right corner of the workflow, use the **Re-run jobs** drop-down menu, and select **Re-run all jobs**.  1. In the upper-right corner of the workflow, use the **Re-run jobs** drop-down menu, and select **Re-run all jobs**.{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}{% else %}{% endif %} 4 content/actions/managing-workflow-runs/removing-workflow-artifacts.md @@ -27,7 +27,11 @@ versions: {% data reusables.repositories.navigate-to-workflow %} {% data reusables.repositories.view-run %} 1. Under **Artifacts**, click {% octicon "trashcan" aria-label="The trashcan icon" %} next to the artifact you want to remove. {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}  {% else %}  {% endif %} {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} ### Setting the retention period for an artifact 23 content/actions/managing-workflow-runs/using-the-visualization-graph.md @@ -0,0 +1,23 @@ --- title: Using the visualization graph intro: Every workflow run generates a real-time graph that illustrates the run progress. You can use this graph to monitor and debug workflows. product: '{% data reusables.gated-features.actions %}' versions: free-pro-team: '*' enterprise-server: '>=3.1' --- {% data reusables.actions.enterprise-beta %} {% data reusables.actions.visualization-beta %} {% data reusables.actions.enterprise-github-hosted-runners %} {% data reusables.repositories.navigate-to-repo %} {% data reusables.repositories.actions-tab %} {% data reusables.repositories.navigate-to-workflow %} {% data reusables.repositories.view-run %} 1. The graph displays each job in the workflow. An icon to the left of the job name indicates the status of the job. Lines between jobs indicate dependencies.  2. Click on a job to view the job log.  18 content/actions/managing-workflow-runs/using-workflow-run-logs.md @@ -45,7 +45,11 @@ You can search the build logs for a particular step. When you search logs, only {% data reusables.repositories.navigate-to-job-superlinter %} {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} 1. In the upper-right corner of the log output, in the **Search logs** search box, type a search query. {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}  {% else %}  {% endif %} {% else %} 1. To expand each step you want to include in your search, click the step.  @@ -63,8 +67,12 @@ You can download the log files from your workflow run. You can also download a w {% data reusables.repositories.view-run-superlinter %} {% data reusables.repositories.navigate-to-job-superlinter %} {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} 1. In the upper right corner, click {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %} and select **Download log archive**. 1. In the upper right corner, click {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}{% octicon "gear" aria-label="The gear icon" %}{% else %}{% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %}{% endif %} and select **Download log archive**. {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}  {% else %}  {% endif %} {% else %} 1. In the upper right corner, click {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %} and select **Download log archive**.  @@ -80,9 +88,17 @@ You can delete the log files from your workflow run. {% data reusables.repositor {% data reusables.repositories.view-run-superlinter %} {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" %} 1. In the upper right corner, click {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %}. {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}  {% else %}  {% endif %} 2. To delete the log files, click the **Delete all logs** button and review the confirmation prompt. {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}  {% else %}  {% endif %} After deleting logs, the **Delete all logs** button is removed to indicate that no log files remain in the workflow run. {% else %} 1. In the upper right corner, click {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %}. 2 content/actions/managing-workflow-runs/viewing-job-execution-time.md @@ -15,7 +15,7 @@ Billable job execution minutes are only shown for jobs run on private repositori {% data reusables.repositories.actions-tab %} {% data reusables.repositories.navigate-to-workflow %} {% data reusables.repositories.view-run %} 1. Under the job summary, you can view the job's execution time. To view the billable job execution time, click **Run and billable time details**. 1. Under the job summary, you can view the job's execution time. To view details about the billable job execution time, click the time under **Billable time**.  {% note %} 5 content/actions/quickstart.md @@ -60,8 +60,13 @@ Committing the workflow file in your repository triggers the `push` event and ru {% data reusables.repositories.actions-tab %} {% data reusables.repositories.navigate-to-workflow-superlinter %} {% data reusables.repositories.view-run-superlinter %} {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %} 1. Under **Jobs** or in the visualization graph, click the **Lint code base** job.  {% else %} 1. In the left sidebar, click the **Lint code base** job.  {% endif %} {% data reusables.repositories.view-failed-job-results-superlinter %} ### More starter workflows 49 content/developers/github-marketplace/about-github-marketplace.md @@ -1,6 +1,6 @@ --- title: About GitHub Marketplace intro: 'Learn the basics to prepare your app for review before joining {% data variables.product.prodname_marketplace %}.' intro: 'Learn about {% data variables.product.prodname_marketplace %} where you can share your apps and actions publicly with all {% data variables.product.product_name %} users.' redirect_from: - /apps/marketplace/getting-started/ - /marketplace/getting-started @@ -14,52 +14,41 @@ versions: {% data reusables.actions.actions-not-verified %} To learn about publishing {% data variables.product.prodname_actions %} in the {% data variables.product.prodname_marketplace %}, see "[Publishing actions in GitHub Marketplace](/actions/creating-actions/publishing-actions-in-github-marketplace)." To learn about publishing {% data variables.product.prodname_actions %} in {% data variables.product.prodname_marketplace %}, see "[Publishing actions in GitHub Marketplace](/actions/creating-actions/publishing-actions-in-github-marketplace)." ### Apps You can list verified and unverified apps in {% data variables.product.prodname_marketplace %}. Unverified apps do not go through the security, testing, and verification cycle {% data variables.product.prodname_dotcom %} requires for verified apps. Anyone can share their apps with other users on {% data variables.product.prodname_marketplace %} but only listings that are verified by {% data variables.product.company_short %} can include paid plans. For more information, see "[About verified creators](/developers/github-marketplace/about-verified-creators)." Verified apps have a green badge in {% data variables.product.prodname_marketplace %}. Unverified apps have a grey badge next to their listing and are only available as free apps. If you're interested in creating an app for {% data variables.product.prodname_marketplace %}, but you're new to {% data variables.product.prodname_github_apps %} or {% data variables.product.prodname_oauth_app %}s, see "[Building {% data variables.product.prodname_github_apps %}](/developers/apps/building-github-apps)" or "[Building {% data variables.product.prodname_oauth_app %}s](/developers/apps/building-oauth-apps)."  If you're interested in creating an app for {% data variables.product.prodname_marketplace %}, but you're new to {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_app %}s, see "[Building apps](/apps/)." {% data reusables.marketplace.github_apps_preferred %}, although you can list both OAuth and {% data variables.product.prodname_github_app %}s in {% data variables.product.prodname_marketplace %}. See "[Differences between GitHub and OAuth apps](/apps/differences-between-apps/)" for more details. To learn more about switching from OAuth to {% data variables.product.prodname_github_apps %}, see [Migrating OAuth Apps to {% data variables.product.prodname_github_app %}s](/apps/migrating-oauth-apps-to-github-apps/). {% data reusables.marketplace.github_apps_preferred %}, although you can list both OAuth and {% data variables.product.prodname_github_app %}s in {% data variables.product.prodname_marketplace %}. For more information, see "[Differences between {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_app %}s](/apps/differences-between-apps/)" and "[Migrating {% data variables.product.prodname_oauth_app %}s to {% data variables.product.prodname_github_apps %}](/apps/migrating-oauth-apps-to-github-apps/)." If you have questions about {% data variables.product.prodname_marketplace %}, please contact {% data variables.contact.contact_support %} directly. #### Unverified Apps Unverified apps do not need to meet the "[Requirements for listing an app on {% data variables.product.prodname_marketplace %}](/marketplace/getting-started/requirements-for-listing-an-app-on-github-marketplace/)" or go through the "[Security review process](/marketplace/getting-started/security-review-process/)". {% data reusables.marketplace.unverified-apps %} Having a published paid plan will prevent you from being able to submit an unverified app. You must remove paid plans or keep them in draft mode before publishing an unverified app. To list your unverified app in {% data variables.product.prodname_marketplace %}, you only need to create a "[Listing on {% data variables.product.prodname_marketplace %}](/marketplace/listing-on-github-marketplace/)" and submit it as an unverified listing. {% data reusables.marketplace.launch-with-free %} ### Publishing an app to {% data variables.product.prodname_marketplace %} #### Verified Apps When you have finished creating your app, you can share it with other users by publishing it to {% data variables.product.prodname_marketplace %}. In summary, the process is: If you've already built an app and you're interested in submitting a verified listing in {% data variables.product.prodname_marketplace %}, start here: 1. Review your app carefully to ensure that it will behave as expected in other repositories and that it follows best practice guidelines. For more information, see "[Security best practices for apps](/developers/github-marketplace/security-best-practices-for-apps)" and "[Requirements for listing an app](/developers/github-marketplace/requirements-for-listing-an-app#best-practice-for-customer-experience)." 1. [Getting started with {% data variables.product.prodname_marketplace %}](/marketplace/getting-started/)<br/>Learn about requirements, guidelines, and the app submission process. 1. Add webhook events to the app to track user billing requests. For more information about the {% data variables.product.prodname_marketplace %} API, webhook events, and billing requests, see "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." 1. [Integrating with the {% data variables.product.prodname_marketplace %} API](/marketplace/integrating-with-the-github-marketplace-api/)<br/>Before you can list your app on {% data variables.product.prodname_marketplace %}, you'll need to integrate billing flows using the {% data variables.product.prodname_marketplace %} API and webhook events. 1. Create a draft {% data variables.product.prodname_marketplace %} listing. For more information, see "[Drafting a listing for your app](/developers/github-marketplace/drafting-a-listing-for-your-app)." 1. [Listing on {% data variables.product.prodname_marketplace %}](/marketplace/listing-on-github-marketplace/) <br/>Create a draft {% data variables.product.prodname_marketplace %} listing, configure webhook settings, and set up pricing plans. 1. Add a pricing plan. For more information, see "[Setting pricing plans for your listing](/developers/github-marketplace/setting-pricing-plans-for-your-listing)." 1. [Selling your app](/marketplace/selling-your-app/)<br/>Learn about pricing plans, billing cycles, and how to receive payment from {% data variables.product.prodname_dotcom %} for your app. 1. Check whether your app meets the requirements for listing on {% data variables.product.prodname_marketplace %} as a free or a paid app. For more information, see "[Requirements for listing an app](/developers/github-marketplace/requirements-for-listing-an-app)." 1. [{% data variables.product.prodname_marketplace %} Insights](/marketplace/github-marketplace-insights/)<br/>See how your app is performing in {% data variables.product.prodname_marketplace %}. You can use metrics collected by {% data variables.product.prodname_dotcom %} to guide your marketing campaign and be successful in {% data variables.product.prodname_marketplace %}. 1. Read and accept the terms of the "[{% data variables.product.prodname_marketplace %} Developer Agreement](/articles/github-marketplace-developer-agreement/)." 1. [{% data variables.product.prodname_marketplace %} transactions](/marketplace/github-marketplace-transactions/)<br/>Download and view transaction data for your {% data variables.product.prodname_marketplace %} listing. 1. Submit your listing for publication in {% data variables.product.prodname_marketplace %}, requesting verification if you want to sell the app. For more information, see "[Submitting your listing for publication](/developers/github-marketplace/submitting-your-listing-for-publication)." ### Reviewing your app An onboarding expert will contact you with any questions or further steps. For example, if you have added a paid plan, you will need to complete the verification process and complete financial onboarding. As soon as your listing is approved the app is published to {% data variables.product.prodname_marketplace %}. We want to make sure that the apps offered on {% data variables.product.prodname_marketplace %} are safe, secure, and well tested. The {% data variables.product.prodname_marketplace %} onboarding specialists will review your app to ensure that it meets all requirements. Follow the guidelines in these articles before submitting your app: ### Seeing how your app is performing You can access metrics and transactions for your listing. For more information, see: * [Requirements for listing an app on {% data variables.product.prodname_marketplace %}](/marketplace/getting-started/requirements-for-listing-an-app-on-github-marketplace/) * [Security review process](/marketplace/getting-started/security-review-process/) - "[Viewing metrics for your listing](/developers/github-marketplace/viewing-metrics-for-your-listing)" - "[Viewing transactions for your listing](/developers/github-marketplace/viewing-transactions-for-your-listing)" 43 content/developers/github-marketplace/about-verified-creators.md @@ -0,0 +1,43 @@ --- title: About verified creators intro: 'Each organization that wants to sell apps on {% data variables.product.prodname_marketplace %} must follow a verification process. Their identity is checked and their billing process reviewed.' versions: free-pro-team: '*' --- ### About verified creators A verified creator is an organization that {% data variables.product.company_short %} has checked. Anyone can share their apps with other users on {% data variables.product.prodname_marketplace %} but only organizations that are verified by {% data variables.product.company_short %} can sell apps. For more information about organizations, see "[About organizations](/github/setting-up-and-managing-organizations-and-teams/about-organizations)." The verification process aims to protect users. For example, it verifies the seller's identity, checks that their {% data variables.product.product_name %} organization is set up securely, and that they can be contacted for support. After passing the verification checks, any apps that the organization lists on {% data variables.product.prodname_marketplace %} are shown with a verified creator badge {% octicon "verified" aria-label="Verified creator badge" %}. The organization can now add paid plans to any of their apps. Each app with a paid plan also goes through a financial onboarding process to check that it's set up to handle billing correctly.  In addition to the verified creator badge, you'll also see badges for unverified and verified apps. These apps were published using the old method for verifying individual apps.  For information on finding apps to use, see "[Searching {% data variables.product.prodname_marketplace %}](/github/searching-for-information-on-github/searching-github-marketplace)." ### About the verification process The first time you request verification for a listing of one of your apps, you will enter the verification process. An onboarding expert will guide you through the process. This includes checking: - Profile information - The basic profile information is populated accurately and appropriately. - Security - The organization has enabled two-factor authentication. - Verified domain - The organization has verified the domain of the site URL. - Purchase webhook event - The event is handled correctly by the app. When your organization is verified, all your apps are shown with a verified creator badge. You are now able to offer paid plans for any of your apps. For more information about the requirements for listing an app on {% data variables.product.prodname_marketplace %}, see "[Requirements for listing an app on {% data variables.product.prodname_marketplace %}](/marketplace/getting-started/requirements-for-listing-an-app-on-github-marketplace/)." {% data reusables.marketplace.app-transfer-to-org-for-verification %} For information on how to do this, see: "[Submitting your listing for publication](/developers/github-marketplace/submitting-your-listing-for-publication#transferring-an-app-to-an-organization-before-you-submit)." {% note %} **Note:** This verification process for apps replaces the previous process where individual apps were verified. The current process is similar to the verification process for actions. If you have apps that were verified under the old process, these will not be affected by the changes. The {% data variables.product.prodname_marketplace %} team will contact you with details of how to migrate to organization-based verification. {% endnote %} 12 content/developers/github-marketplace/billing-customers.md @@ -13,17 +13,17 @@ versions: ### Understanding the billing cycle Customers can choose a monthly or yearly billing cycle when they purchase your app. All changes customers make to the billing cycle and plan selection will trigger a `marketplace_purchase` event. You can refer to the `marketplace_purchase` webhook payload to see which billing cycle a customer selects and when the next billing date begins (`effective_date`). For more information about webhook payloads, see "[{% data variables.product.prodname_marketplace %} webhook events](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/)." Customers can choose a monthly or yearly billing cycle when they purchase your app. All changes customers make to the billing cycle and plan selection will trigger a `marketplace_purchase` event. You can refer to the `marketplace_purchase` webhook payload to see which billing cycle a customer selects and when the next billing date begins (`effective_date`). For more information about webhook payloads, see "[Webhook events for the {% data variables.product.prodname_marketplace %} API](/developers/github-marketplace/webhook-events-for-the-github-marketplace-api)." ### Providing billing services in your app's UI Customers must be able to perform the following actions from your app's website: - Customers must be able to modify or cancel their {% data variables.product.prodname_marketplace %} plans for personal and organizational accounts separately. Customers should be able to perform the following actions from your app's website: - Customers should be able to modify or cancel their {% data variables.product.prodname_marketplace %} plans for personal and organizational accounts separately. {% data reusables.marketplace.marketplace-billing-ui-requirements %} ### Billing services for upgrades, downgrades, and cancellations Follow these guidelines for upgrades, downgrades, and cancellations to maintain a clear and consistent billing process. For more detailed instructions about the {% data variables.product.prodname_marketplace %} purchase events, see "[Billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows)." Follow these guidelines for upgrades, downgrades, and cancellations to maintain a clear and consistent billing process. For more detailed instructions about the {% data variables.product.prodname_marketplace %} purchase events, see "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." You can use the `marketplace_purchase` webhook's `effective_date` key to determine when a plan change will occur and periodically synchronize the [List accounts for a plan](/rest/reference/apps#list-accounts-for-a-plan). @@ -33,7 +33,7 @@ When a customer upgrades their pricing plan or changes their billing cycle from {% data reusables.marketplace.marketplace-failed-purchase-event %} For information about building upgrade and downgrade workflows into your app, see "[Upgrading and downgrading plans](/marketplace/integrating-with-the-github-marketplace-api/upgrading-and-downgrading-plans/)." For information about building upgrade and downgrade workflows into your app, see "[Handling plan changes](/developers/github-marketplace/handling-plan-changes)." #### Downgrades and cancellations @@ -45,4 +45,4 @@ When a customer cancels a plan, you must: {% data reusables.marketplace.cancellation-clarification %} - Enable them to upgrade the plan through GitHub if they would like to continue the plan at a later time. For information about building cancellation workflows into your app, see "[Cancelling plans](/marketplace/integrating-with-the-github-marketplace-api/cancelling-plans/)." For information about building cancellation workflows into your app, see "[Handling plan cancellations](/developers/github-marketplace/handling-plan-cancellations)." 20 ...nt/developers/github-marketplace/customer-experience-best-practices-for-apps.md @@ -0,0 +1,20 @@ --- title: Customer experience best practices for apps intro: 'Guidelines for creating an app that will be easy to use and understand.' shortTitle: Customer experience best practice versions: free-pro-team: '*' --- If you follow these best practices it will help you to provide a good customer experience. ### Customer communication - Marketing materials for the app should accurately represent the app's behavior. - Apps should include links to user-facing documentation that describe how to set up and use the app. - Customers should be able to see what type of plan they have in the billing, profile, or account settings section of the app. - Customers should be able to install and use your app on both a personal account and an organization account. They should be able to view and manage the app on those accounts separately. ### Plan management {% data reusables.marketplace.marketplace-billing-ui-requirements %} 4 content/developers/github-marketplace/drafting-a-listing-for-your-app.md @@ -59,8 +59,8 @@ Once you've created a {% data variables.product.prodname_marketplace %} draft li ### Submitting your app Once you've completed your {% data variables.product.prodname_marketplace %} listing, you can submit your listing for review from the **Overview** page. You'll need to read and accept the "[{% data variables.product.prodname_marketplace %} Developer Agreement](/articles/github-marketplace-developer-agreement/)," and then you can click **Submit for review**. After you submit your app for review, the {% data variables.product.prodname_marketplace %} onboarding team will contact you with additional information about the onboarding process. You can learn more about the onboarding and security review process in "[Getting started with {% data variables.product.prodname_marketplace %}](/marketplace/getting-started/)." Once you've completed your {% data variables.product.prodname_marketplace %} listing, you can submit your listing for review from the **Overview** page. You'll need to read and accept the "[{% data variables.product.prodname_marketplace %} Developer Agreement](/articles/github-marketplace-developer-agreement/)," and then you can click **Submit for review**. After you submit your app for review, an onboarding expert will contact you with additional information about the onboarding process. You can learn more about the onboarding and security review process in "[Getting started with {% data variables.product.prodname_marketplace %}](/marketplace/getting-started/)." ### Removing a {% data variables.product.prodname_marketplace %} listing If you no longer want to list your app in {% data variables.product.prodname_marketplace %}, contact [marketplace@github.com](mailto:marketplace@github.com) to remove your listing. If you no longer want to list your app in {% data variables.product.prodname_marketplace %}, contact {% data variables.contact.contact_support %} to remove your listing. 2 content/developers/github-marketplace/handling-new-purchases-and-free-trials.md @@ -28,7 +28,7 @@ GitHub then sends the [`marketplace_purchase`](/webhooks/event-payloads/#marketp Read the `effective_date` and `marketplace_purchase` object from the `marketplace_purchase` webhook to determine which plan the customer purchased, when the billing cycle starts, and when the next billing cycle begins. If your app offers a free trial, read the `marketplace_purchase[on_free_trial]` attribute from the webhook. If the value is `true`, your app will need to track the free trial start date (`effective_date`) and the date the free trial ends (`free_trial_ends_on`). Use the `free_trial_ends_on` date to display the remaining days left in a free trial in your app's UI. You can do this in either a banner or in your [billing UI](/marketplace/selling-your-app/billing-customers-in-github-marketplace/#providing-billing-services-in-your-apps-ui). To learn how to handle cancellations before a free trial ends, see "[Cancelling plans](/marketplace/integrating-with-the-github-marketplace-api/cancelling-plans/)." See "[Upgrading and downgrading plans](/marketplace/integrating-with-the-github-marketplace-api/upgrading-and-downgrading-plans/)" to find out how to transition a free trial to a paid plan when a free trial expires. If your app offers a free trial, read the `marketplace_purchase[on_free_trial]` attribute from the webhook. If the value is `true`, your app will need to track the free trial start date (`effective_date`) and the date the free trial ends (`free_trial_ends_on`). Use the `free_trial_ends_on` date to display the remaining days left in a free trial in your app's UI. You can do this in either a banner or in your [billing UI](/marketplace/selling-your-app/billing-customers-in-github-marketplace/#providing-billing-services-in-your-apps-ui). To learn how to handle cancellations before a free trial ends, see "[Handling plan cancellations](/developers/github-marketplace/handling-plan-cancellations)." See "[Handling plan changes](/developers/github-marketplace/handling-plan-changes)" to find out how to transition a free trial to a paid plan when a free trial expires. See "[{% data variables.product.prodname_marketplace %} webhook events](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/)" for an example of the `marketplace_purchase` event payload. 6 content/developers/github-marketplace/index.md @@ -11,8 +11,10 @@ versions: {% topic_link_in_list /creating-apps-for-github-marketplace %} {% link_in_list /about-github-marketplace %} {% link_in_list /about-verified-creators %} {% link_in_list /requirements-for-listing-an-app %} {% link_in_list /security-review-process-for-submitted-apps %} {% link_in_list /security-best-practices-for-apps %} {% link_in_list /customer-experience-best-practices-for-apps %} {% link_in_list /viewing-metrics-for-your-listing %} {% link_in_list /viewing-transactions-for-your-listing %} {% topic_link_in_list /using-the-github-marketplace-api-in-your-app %} @@ -27,7 +29,7 @@ versions: {% link_in_list /writing-a-listing-description-for-your-app %} {% link_in_list /setting-pricing-plans-for-your-listing %} {% link_in_list /configuring-a-webhook-to-notify-you-of-plan-changes %} {% link_in_list /submitting-your-listing-for-review %} {% link_in_list /submitting-your-listing-for-publication %} {% topic_link_in_list /selling-your-app-on-github-marketplace %} {% link_in_list /pricing-plans-for-github-marketplace-apps %} {% link_in_list /billing-customers %} 32 content/developers/github-marketplace/pricing-plans-for-github-marketplace-apps.md @@ -10,35 +10,45 @@ versions: {% data variables.product.prodname_marketplace %} pricing plans can be free, flat rate, or per-unit, and GitHub lists the price in US dollars. Customers purchase your app using a payment method attached to their {% data variables.product.product_name %} account, without having to leave GitHub.com. You don't have to write code to perform billing transactions, but you will have to handle [billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows) for purchase events. {% data variables.product.prodname_marketplace %} pricing plans can be free, flat rate, or per-unit. Prices are set, displayed, and processed in US dollars. Paid plans are restricted to verified listings. Customers purchase your app using a payment method attached to their {% data variables.product.product_name %} account, without having to leave {% data variables.product.prodname_dotcom_the_website %}. You don't have to write code to perform billing transactions, but you will have to handle events from the {% data variables.product.prodname_marketplace %} API. For more information, see "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." If the app you're listing on {% data variables.product.prodname_marketplace %} has multiple plan options, you can set up corresponding pricing plans. For example, if your app has two plan options, an open source plan and a pro plan, you can set up a free pricing plan for your open source plan and a flat pricing plan for your pro plan. Each {% data variables.product.prodname_marketplace %} listing must have an annual and a monthly price for every plan that's listed. For more information on how to create a pricing plan, see "[Setting a {% data variables.product.prodname_marketplace %} listing's pricing plan](/marketplace/listing-on-github-marketplace/setting-a-github-marketplace-listing-s-pricing-plan/)." {% note %} {% data reusables.marketplace.free-plan-note %} **Note:** If you're listing an app on {% data variables.product.prodname_marketplace %}, you can't list your app with a free pricing plan if you offer a paid service outside of {% data variables.product.prodname_marketplace %}. ### Types of pricing plans {% endnote %} #### Free pricing plans ### Types of pricing plans {% data reusables.marketplace.free-apps-encouraged %} Free plans are completely free for users. If you set up a free pricing plan, you cannot charge users that choose the free pricing plan for the use of your app. You can create both free and paid plans for your listing. All apps need to handle events for new purchases and cancellations. Apps that only have free plans do not need to handle events for free trials, upgrades, and downgrades. For more information, see: "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." If you add a paid plan to an app that you've already listed in {% data variables.product.prodname_marketplace %} as a free service, you'll need to request verification for the app and go through financial onboarding. #### Paid pricing plans **Free pricing plans** are completely free for users. If you set up a free pricing plan, you cannot charge users that choose the free pricing plan for the use of your app. You can create both free and paid plans for your listing. Unverified free apps do not need to implement any billing flows. Free apps that are verified by Github need to implement billing flows for new purchases and cancellations, but do not need to implement billing flows for free trials, upgrades, and downgrades. If you add a paid plan to an app that you've already listed in {% data variables.product.prodname_marketplace %} as a free service, you'll need to resubmit the app for review. There are two types of paid pricing plan: **Flat rate pricing plans** charge a set fee on a monthly and yearly basis. - Flat rate pricing plans charge a set fee on a monthly and yearly basis. **Per-unit pricing plans** charge a set fee on either a monthly or yearly basis for a unit that you specify. A "unit" can be anything you'd like (for example, a user, seat, or person). - Per-unit pricing plans charge a set fee on either a monthly or yearly basis for a unit that you specify. A "unit" can be anything you'd like (for example, a user, seat, or person). **Marketplace free trials** provide 14-day free trials of OAuth or GitHub Apps to customers. When you [set up a Marketplace pricing plan](/marketplace/listing-on-github-marketplace/setting-a-github-marketplace-listing-s-pricing-plan/), you can select the option to provide a free trial for flat-rate or per-unit pricing plans. You may also want to offer free trials. These provide free, 14-day trials of OAuth or GitHub Apps to customers. When you set up a Marketplace pricing plan, you can select the option to provide a free trial for flat-rate or per-unit pricing plans. ### Free trials Customers can start a free trial for any available paid plan on a Marketplace listing, but will not be able to create more than one free trial for a Marketplace product. Customers can start a free trial for any paid plan on a Marketplace listing that includes free trials. However, customers cannot create more than one free trial per marketplace product. Free trials have a fixed length of 14 days. Customers are notified 4 days before the end of their trial period (on day 11 of the free trial) that their plan will be upgraded. At the end of a free trial, customers will be auto-enrolled into the plan they are trialing if they do not cancel. See "[New purchases and free trials](/marketplace/integrating-with-the-github-marketplace-api/handling-new-purchases-and-free-trials/)" for details on how to handle free trials in your app. For more information, see: "[Handling new purchases and free trials](/developers/github-marketplace/integrating-with-the-github-marketplace-api/handling-new-purchases-and-free-trials/)." {% note %} 61 content/developers/github-marketplace/requirements-for-listing-an-app.md @@ -1,6 +1,6 @@ --- title: Requirements for listing an app intro: 'Apps on {% data variables.product.prodname_marketplace %} must meet the requirements outlined on this page before our {% data variables.product.prodname_marketplace %} onboarding specialists will approve the listing.' intro: 'Apps on {% data variables.product.prodname_marketplace %} must meet the requirements outlined on this page before the listing can be published.' redirect_from: - /apps/adding-integrations/listing-apps-on-github-marketplace/requirements-for-listing-an-app-on-github-marketplace/ - /apps/marketplace/listing-apps-on-github-marketplace/requirements-for-listing-an-app-on-github-marketplace/ @@ -12,49 +12,62 @@ versions: free-pro-team: '*' --- <!--UI-LINK: Displayed as a link on the https://github.com/marketplace/new page.--> The requirements for listing an app on {% data variables.product.prodname_marketplace %} vary according to whether you want to offer a free or a paid app. Before you submit your app for review, you must read and accept the terms of the "[{% data variables.product.prodname_marketplace %} Developer Agreement](/articles/github-marketplace-developer-agreement/)." You'll accept the terms within your [draft listing](/marketplace/listing-on-github-marketplace/creating-a-draft-github-marketplace-listing/) on {% data variables.product.product_name %}. Once you've submitted your app, one of the {% data variables.product.prodname_marketplace %} onboarding specialists will reach out to you with more information about the onboarding process, and review your app to ensure it meets these requirements: ### Requirements for all {% data variables.product.prodname_marketplace %} listings ### User experience All listings on {% data variables.product.prodname_marketplace %} should be for tools that provide value to the {% data variables.product.product_name %} community. When you submit your listing for publication, you must read and accept the terms of the "[{% data variables.product.prodname_marketplace %} Developer Agreement](/articles/github-marketplace-developer-agreement/)." - {% data variables.product.prodname_github_app %}s should have a minimum of 100 installations. - {% data variables.product.prodname_oauth_app %}s should have a minimum of 200 users. #### User experience requirements for all apps All listings should meet the following requirements, regardless of whether they are for a free or paid app. - Listings must not actively persuade users away from {% data variables.product.product_name %}. - Listings must include valid contact information for the publisher. - Listings must have a relevant description of the application. - Listings must specify a pricing plan. - Apps must provide value to customers and integrate with the platform in some way beyond authentication. - Apps must be publicly available in {% data variables.product.prodname_marketplace %} and cannot be in beta or available by invite only. - Apps cannot actively persuade users away from {% data variables.product.product_name %}. - Marketing materials for the app must accurately represent the app's behavior. - Apps must include links to user-facing documentation that describe how to set up and use the app. - When a customer purchases an app and GitHub redirects them to the app's installation URL, the app must begin the OAuth flow immediately. For details, see "[Handling new purchases and free trials](/marketplace/integrating-with-the-github-marketplace-api/handling-new-purchases-and-free-trials/#step-3-authorization)." - Apps must have webhook events set up to notify the publisher of any plan changes or cancellations using the {% data variables.product.prodname_marketplace %} API. For more information, see "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." - Customers must be able to install your app and select repositories on both a personal and organization account. They should be able to view and manage those accounts separately. For more information on providing a good customer experience, see "[Customer experience best practices for apps](/developers/github-marketplace/customer-experience-best-practices-for-apps)." ### Brand and listing #### Brand and listing requirements for all apps - Apps that use GitHub logos must follow the "[{% data variables.product.product_name %} Logos and Usage](https://github.com/logos)" guidelines. - Apps that use GitHub logos must follow the {% data variables.product.company_short %} guidelines. For more information, see "[{% data variables.product.company_short %} Logos and Usage](https://github.com/logos)." - Apps must have a logo, feature card, and screenshots images that meet the recommendations provided in "[Writing {% data variables.product.prodname_marketplace %} listing descriptions](/marketplace/listing-on-github-marketplace/writing-github-marketplace-listing-descriptions/)." - Listings must include descriptions that are well written and free of grammatical errors. For guidance in writing your listing, see "[Writing {% data variables.product.prodname_marketplace %} listing descriptions](/marketplace/listing-on-github-marketplace/writing-github-marketplace-listing-descriptions/)." ### Security To protect your customers, we recommend that you also follow security best practices. For more information, see "[Security best practices for apps](/developers/github-marketplace/security-best-practices-for-apps)." ### Considerations for free apps Apps will go through a security review before being listed on {% data variables.product.prodname_marketplace %}. A successful review will meet the requirements and follow the security best practices listed in "[Security review process](/marketplace/getting-started/security-review-process/)." For information on the review process, contact [marketplace@github.com](mailto:marketplace@github.com). {% data reusables.marketplace.free-apps-encouraged %} ### Requirements for paid apps In addition to the requirements for all apps above, each app that you offer as a paid service on {% data variables.product.prodname_marketplace %} must also meet the following requirements: - {% data variables.product.prodname_github_app %}s should have a minimum of 100 installations. - {% data variables.product.prodname_oauth_app %}s should have a minimum of 200 users. - All paid apps must handle {% data variables.product.prodname_marketplace %} purchase events for new purchases, upgrades, downgrades, cancellations, and free trials. For more information, see "[Billing requirements for paid apps](#billing-requirements-for-paid-apps)" below. - Publishing organizations must have a verified domain and must enable two-factor authentication. For more information, see "[Requiring two-factor authentication in your organization](/github/setting-up-and-managing-organizations-and-teams/requiring-two-factor-authentication-in-your-organization.") ### Billing flows When you are ready to publish the app on {% data variables.product.prodname_marketplace %} you must request verification for the listing. Your app must integrate [billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows) using the [{% data variables.product.prodname_marketplace %} webhook event](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/). {% note %} #### Free apps The verification process is open to organizations. {% data reusables.marketplace.app-transfer-to-org-for-verification %} For information on how to do this, see: "[Submitting your listing for publication](/developers/github-marketplace/submitting-your-listing-for-publication#transferring-an-app-to-an-organization-before-you-submit)." {% data reusables.marketplace.free-apps-encouraged %} If you are listing a free app, you'll need to meet these requirements: {% endnote %} - Customers must be able to see that they have a free plan in the billing, profile, or account settings section of the app. - When a customer cancels your app, you must follow the flow for [cancelling plans](/marketplace/integrating-with-the-github-marketplace-api/cancelling-plans/). ### Billing requirements for paid apps #### Paid apps Your app does not need to handle payments but does need to use {% data variables.product.prodname_marketplace %} purchase events to manage new purchases, upgrades, downgrades, cancellations, and free trials. For information about how integrate these events into your app, see "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." To offer your app as a paid service, you'll need to meet these requirements to list your app on {% data variables.product.prodname_marketplace %}: Using GitHub's billing API allows customers to purchase an app without leaving GitHub and to pay for the service with the payment method already attached to their {% data variables.product.product_name %} account. - To sell your app in {% data variables.product.prodname_marketplace %}, it must use GitHub's billing system. Your app does not need to handle payments but does need to use "[{% data variables.product.prodname_marketplace %} purchase events](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/)" to manage new purchases, upgrades, downgrades, cancellations, and free trials. See "[Billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows)" to learn about how to integrate these events into your app. Using GitHub's billing system allows customers to purchase an app without leaving GitHub and pay for the service with the payment method already attached to their {% data variables.product.product_name %} account. - Apps must support both monthly and annual billing for paid subscriptions purchases. - Listings may offer any combination of free and paid plans. Free plans are optional but encouraged. For more information, see "[Setting a {% data variables.product.prodname_marketplace %} listing's pricing plan](/marketplace/listing-on-github-marketplace/setting-a-github-marketplace-listing-s-pricing-plan/)." {% data reusables.marketplace.marketplace-billing-ui-requirements %} 60 content/developers/github-marketplace/security-best-practices-for-apps.md @@ -0,0 +1,60 @@ --- title: Security best practices for apps intro: 'Guidelines for preparing a secure app to share on {% data variables.product.prodname_marketplace %}.' redirect_from: - /apps/marketplace/getting-started/security-review-process/ - /marketplace/getting-started/security-review-process - /developers/github-marketplace/security-review-process-for-submitted-apps shortTitle: Security best practice versions: free-pro-team: '*' --- If you follow these best practices it will help you to provide a secure user experience. ### Authorization, authentication, and access control We recommend creating a GitHub App rather than an OAuth App. {% data reusables.marketplace.github_apps_preferred %}. See "[Differences between GitHub Apps and OAuth Apps](/apps/differences-between-apps/)" for more details. - Apps should use the principle of least privilege and should only request the OAuth scopes and GitHub App permissions that the app needs to perform its intended functionality. For more information, see [Principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) in Wikipedia. - Apps should provide customers with a way to delete their account, without having to email or call a support person. - Apps should not share tokens between different implementations of the app. For example, a desktop app should have a separate token from a web-based app. Individual tokens allow each app to request the access needed for GitHub resources separately. - Design your app with different user roles, depending on the functionality needed by each type of user. For example, a standard user should not have access to admin functionality, and billing managers might not need push access to repository code. - Apps should not share service accounts such as email or database services to manage your SaaS service. - All services used in your app should have unique login and password credentials. - Admin privilege access to the production hosting infrastructure should only be given to engineers and employees with administrative duties. - Apps should not use personal access tokens to authenticate and should authenticate as an [OAuth App](/apps/about-apps/#about-oauth-apps) or a [GitHub App](/apps/about-apps/#about-github-apps): - OAuth Apps should authenticate using an [OAuth token](/apps/building-oauth-apps/authorizing-oauth-apps/). - GitHub Apps should authenticate using either a [JSON Web Token (JWT)](/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app), [OAuth token](/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps/), or [installation access token](/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-an-installation). ### Data protection - Apps should encrypt data transferred over the public internet using HTTPS, with a valid TLS certificate, or SSH for Git. - Apps should store client ID and client secret keys securely. We recommend storing them as [environmental variables](http://en.wikipedia.org/wiki/Environment_variable#Getting_and_setting_environment_variables). - Apps should delete all GitHub user data within 30 days of receiving a request from the user, or within 30 days of the end of the user's legal relationship with GitHub. - Apps should not require the user to provide their GitHub password. - Apps should encrypt tokens, client IDs, and client secrets. ### Logging and monitoring Apps should have logging and monitoring capabilities. App logs should be retained for at least 30 days and archived for at least one year. A security log should include: - Authentication and authorization events - Service configuration changes - Object reads and writes - All user and group permission changes - Elevation of role to admin - Consistent timestamping for each event - Source users, IP addresses, and/or hostnames for all logged actions ### Incident response workflow To provide a secure experience for users, you should have a clear incident response plan in place before listing your app. We recommend having a security and operations incident response team in your company rather than using a third-party vendor. You should have the capability to notify {% data variables.product.product_name %} within 24 hours of a confirmed incident. For an example of an incident response workflow, see the "Data Breach Response Policy" on the [SANS Institute website](https://www.sans.org/information-security-policy/). A short document with clear steps to take in the event of an incident is more valuable than a lengthy policy template. ### Vulnerability management and patching workflow You should conduct regular vulnerability scans of production infrastructure. You should triage the results of vulnerability scans and define a period of time in which you agree to remediate the vulnerability. If you are not ready to set up a full vulnerability management program, it's useful to start by creating a patching process. For guidance in creating a patch management policy, see this TechRepublic article "[Establish a patch management policy](https://www.techrepublic.com/blog/it-security/establish-a-patch-management-policy-87756/)." 94 ...ent/developers/github-marketplace/security-review-process-for-submitted-apps.md This file was deleted. 53 content/developers/github-marketplace/setting-pricing-plans-for-your-listing.md @@ -1,6 +1,6 @@ --- title: Setting pricing plans for your listing intro: 'When [listing your app on {% data variables.product.prodname_marketplace %}](/marketplace/listing-on-github-marketplace/), you can choose to provide your app as a free service or sell your app. If you plan to sell your app, you can create different pricing plans for different feature tiers.' intro: 'When you list your app on {% data variables.product.prodname_marketplace %}, you can choose to provide your app as a free service or sell your app. If you plan to sell your app, you can create different pricing plans for different feature tiers.' redirect_from: - /apps/adding-integrations/managing-pricing-and-payments-for-a-github-marketplace-listing/setting-a-github-marketplace-listing-s-pricing-plan/ - /apps/marketplace/managing-pricing-and-payments-for-a-github-marketplace-listing/setting-a-github-marketplace-listing-s-pricing-plan/ @@ -17,57 +17,52 @@ versions: free-pro-team: '*' --- ### About setting pricing plans If you want to sell an app on {% data variables.product.prodname_marketplace %}, you need to request verification when you publish the listing for your app. During the verification process, an onboarding expert checks the organization's identity and security settings. The onboarding expert will also take the organization through financial onboarding. For more information, see: "[Requirements for listing an app on {% data variables.product.prodname_marketplace %}](/marketplace/getting-started/requirements-for-listing-an-app-on-github-marketplace/)." ### Creating pricing plans To learn about the types of pricing plans that {% data variables.product.prodname_marketplace %} offers, see "[{% data variables.product.prodname_marketplace %} Pricing Plans](/marketplace/selling-your-app/github-marketplace-pricing-plans/)." You'll also find helpful billing guidelines in "[Selling your app](/marketplace/selling-your-app/)." Pricing plans can be in the draft or published state. If you haven't submitted your {% data variables.product.prodname_marketplace %} listing for approval, a published listing will function the same way as draft listings until your app is approved and listed on {% data variables.product.prodname_marketplace %}. Draft listings allow you to create and save new pricing plans without making them available on your {% data variables.product.prodname_marketplace %} listing page. Once you publish the pricing plan, it's available for customers to purchase immediately. You can publish up to 10 pricing plans. {% data reusables.marketplace.app-transfer-to-org-for-verification %} For information on how to do this, see: "[Submitting your listing for publication](/developers/github-marketplace/submitting-your-listing-for-publication#transferring-an-app-to-an-organization-before-you-submit)." To create a pricing plan for your {% data variables.product.prodname_marketplace %} listing, click **Plans and pricing** in the left sidebar of your [{% data variables.product.prodname_marketplace %} listing page](https://github.com/marketplace/manage). If you haven't created a {% data variables.product.prodname_marketplace %} listing yet, read "[Creating a draft {% data variables.product.prodname_marketplace %} listing](/marketplace/listing-on-github-marketplace/creating-a-draft-github-marketplace-listing/)" to learn how. When you click **New draft plan**, you'll see a form that allows you to customize your pricing plan. You'll need to configure the following fields to create a pricing plan: {% data variables.product.prodname_marketplace %} offers several different types of pricing plan. For detailed information, see "[Pricing plans for {% data variables.product.prodname_marketplace %}](/developers/github-marketplace/pricing-plans-for-github-marketplace-apps)." #### Plan name ### About saving pricing plans Your pricing plan's name will appear on your {% data variables.product.prodname_marketplace %} app's landing page. You can customize the name of your pricing plan to align to the plan's resources, the size of the company that will use the plan, or anything you'd like. You can save pricing plans in a draft or published state. If you haven't submitted your {% data variables.product.prodname_marketplace %} listing for approval, a published plan will function in the same way as a draft plan until your listing is approved and shown on {% data variables.product.prodname_marketplace %}. Draft plans allow you to create and save new pricing plans without making them available on your {% data variables.product.prodname_marketplace %} listing page. Once you publish a pricing plan on a published listing, it's available for customers to purchase immediately. You can publish up to 10 pricing plans. #### Pricing models For guidelines on billing customers, see "[Billing customers](/developers/github-marketplace/billing-customers)." ##### Free plans {% data reusables.marketplace.free-apps-encouraged %} A free plan still requires you to handle [new purchase](/marketplace/integrating-with-the-github-marketplace-api/handling-new-purchases-and-free-trials/) and [cancellation](/marketplace/integrating-with-the-github-marketplace-api/cancelling-plans/) billing flows. See "[Billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows)" for more details. ##### Flat-rate plans ### Creating pricing plans Flat-rate pricing plans allow you to offer your service to customers for a flat-rate fee. {% data reusables.marketplace.marketplace-pricing-free-trials %} To create a pricing plan for your {% data variables.product.prodname_marketplace %} listing, click **Plans and pricing** in the left sidebar of your [{% data variables.product.prodname_marketplace %} listing page](https://github.com/marketplace/manage). For more information, see "[Creating a draft {% data variables.product.prodname_marketplace %} listing](/marketplace/listing-on-github-marketplace/creating-a-draft-github-marketplace-listing/)." You must set a price for both monthly and yearly subscriptions in U.S. Dollars for flat-rate plans. When you click **New draft plan**, you'll see a form that allows you to customize your pricing plan. You'll need to configure the following fields to create a pricing plan: ##### Per-unit plans - **Plan name** - Your pricing plan's name will appear on your {% data variables.product.prodname_marketplace %} app's landing page. You can customize the name of your pricing plan to align with the plan's resources, the size of the company that will use the plan, or anything you'd like. Per-unit pricing allows you to offer your app in units. For example, a unit can be a person, seat, or user. You'll need to provide a name for the unit and set a price for both monthly and yearly subscriptions, in U.S. Dollars. - **Pricing models** - There are three types of pricing plan: free, flat-rate, and per-unit. All plans require you to process new purchase and cancellation events from the marketplace API. In addition, for paid plans: #### Available for - You must set a price for both monthly and yearly subscriptions in US dollars. - Your app must process plan change events. - You must request verification to publish a listing with a paid plan. - {% data reusables.marketplace.marketplace-pricing-free-trials %} {% data variables.product.prodname_marketplace %} pricing plans can apply to **Personal and organization accounts**, **Personal accounts only**, or **Organization accounts only**. For example, if your pricing plan is per-unit and provides multiple seats, you would select **Organization accounts only** because there is no way to assign seats to people in an organization from a personal account. For detailed information, see "[Pricing plans for {% data variables.product.prodname_marketplace %} apps](/developers/github-marketplace/pricing-plans-for-github-marketplace-apps)" and "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." #### Short description - **Available for** - {% data variables.product.prodname_marketplace %} pricing plans can apply to **Personal and organization accounts**, **Personal accounts only**, or **Organization accounts only**. For example, if your pricing plan is per-unit and provides multiple seats, you would select **Organization accounts only** because there is no way to assign seats to people in an organization from a personal account. Write a brief summary of the details of the pricing plan. The description might include the type of customer the plan is intended for or the resources the plan includes. - **Short description** - Write a brief summary of the details of the pricing plan. The description might include the type of customer the plan is intended for or the resources the plan includes. #### Bullets - **Bullets** - You can write up to four bullets that include more details about your pricing plan. The bullets might include the use cases of your app or list more detailed information about the resources or features included in the plan. You can write up to four bullets that include more details about your pricing plan. The bullets might include the use cases of your app or list more detailed information about the resources or features included in the plan. {% data reusables.marketplace.free-plan-note %} ### Changing a {% data variables.product.prodname_marketplace %} listing's pricing plan If a pricing plan for your {% data variables.product.prodname_marketplace %} plan is no longer needed or if you need to adjust pricing details, you can remove it. If a pricing plan for your {% data variables.product.prodname_marketplace %} listing is no longer needed, or if you need to adjust pricing details, you can remove it.  Once you publish a pricing plan for an app already listed in the {% data variables.product.prodname_marketplace %}, you can't make changes to the plan. Instead, you'll need to remove the pricing plan. Customers who already purchased the removed pricing plan will continue to use it until they opt out and move onto a new pricing plan. For more on pricing plans, see "[{% data variables.product.prodname_marketplace %} pricing plans](/marketplace/selling-your-app/github-marketplace-pricing-plans/)." Once you publish a pricing plan for an app that is already listed in {% data variables.product.prodname_marketplace %}, you can't make changes to the plan. Instead, you'll need to remove the pricing plan and create a new plan. Customers who already purchased the removed pricing plan will continue to use it until they opt out and move onto a new pricing plan. For more on pricing plans, see "[{% data variables.product.prodname_marketplace %} pricing plans](/marketplace/selling-your-app/github-marketplace-pricing-plans/)." Once you remove a pricing plan, users won't be able to purchase your app using that plan. Existing users on the removed pricing plan will continue to stay on the plan until they cancel their plan subscription. 37 content/developers/github-marketplace/submitting-your-listing-for-publication.md @@ -0,0 +1,37 @@ --- title: Submitting your listing for publication intro: 'You can submit your listing for the {% data variables.product.prodname_dotcom %} community to use.' redirect_from: - /marketplace/listing-on-github-marketplace/submitting-your-listing-for-review - /developers/github-marketplace/submitting-your-listing-for-review versions: free-pro-team: '*' --- Once you've completed the listing for your app, you'll see two buttons that allow you to request publication of the listing with or without verification. The **Request** button for "Publish without verification" is disabled if you have published any paid pricing plans in the listing.  {% data reusables.marketplace.launch-with-free %} After you submit your listing for review, an onboarding expert will reach out to you with additional information. For an overview of the process for creating and submitting a listing, see "[About {% data variables.product.prodname_marketplace %}](/developers/github-marketplace/about-github-marketplace#publishing-an-app-to-github-marketplace)." ### Prerequisites for publishing with verification Before you request verification of your listing, you'll need to integrate the {% data variables.product.prodname_marketplace %} billing flows and webhook into your app. For more information, see "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." If you've met the requirements for listing and you've integrated with the {% data variables.product.prodname_marketplace %} API, go ahead and submit your listing. For more information, see "[Requirements for listing an app](/developers/github-marketplace/requirements-for-listing-an-app)." {% data reusables.marketplace.app-transfer-to-org-for-verification %} For information on how to do this, see: "[Transferring an app to an organization before you submit](#transferring-an-app-to-an-organization-before-you-submit)" below. ### Transferring an app to an organization before you submit You cannot sell an app that's owned by a user account. You need to transfer the app to an organization that is already a verified creator, or that can request verification for a listing for the app. For details, see: 1. "[Creating an organization from scratch](/github/setting-up-and-managing-organizations-and-teams/creating-a-new-organization-from-scratch)" 1. "[Transferring ownership of a GitHub App](/developers/apps/transferring-ownership-of-a-github-app)" or "[Transferring ownership of an OAuth App](/developers/apps/transferring-ownership-of-an-oauth-app)" 22 content/developers/github-marketplace/submitting-your-listing-for-review.md This file was deleted. 4 content/developers/github-marketplace/testing-your-app.md @@ -1,6 +1,6 @@ --- title: Testing your app intro: 'GitHub recommends testing your app with APIs and webhooks before submitting your listing to {% data variables.product.prodname_marketplace %} so you can provide an ideal experience for customers. Before the {% data variables.product.prodname_marketplace %} onboarding team approves your app, it must adequately handle the [billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows).' intro: 'GitHub recommends testing your app with APIs and webhooks before submitting your listing to {% data variables.product.prodname_marketplace %} so you can provide an ideal experience for customers. Before an onboarding expert approves your app, it must adequately handle the billing flows.' redirect_from: - /apps/marketplace/testing-apps-apis-and-webhooks/ - /apps/marketplace/integrating-with-the-github-marketplace-api/testing-github-marketplace-apps/ @@ -13,7 +13,7 @@ versions: ### Testing apps You can use a [draft {% data variables.product.prodname_marketplace %} listing](/marketplace/listing-on-github-marketplace/creating-a-draft-github-marketplace-listing/) to simulate each of the [billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows). A listing in the draft state means that it has not been submitted for approval. Any purchases you make using a draft {% data variables.product.prodname_marketplace %} listing will _not_ create real transactions, and GitHub will not charge your credit card. You can use a draft {% data variables.product.prodname_marketplace %} listing to simulate each of the billing flows. A listing in the draft state means that it has not been submitted for approval. Any purchases you make using a draft {% data variables.product.prodname_marketplace %} listing will _not_ create real transactions, and GitHub will not charge your credit card. For more information, see "[Drafting a listing for your app](/developers/github-marketplace/drafting-a-listing-for-your-app)" and "[Using the {% data variables.product.prodname_marketplace %} API in your app](/developers/github-marketplace/using-the-github-marketplace-api-in-your-app)." #### Using a development app with a draft listing to test changes 2 .../developers/github-marketplace/webhook-events-for-the-github-marketplace-api.md @@ -1,6 +1,6 @@ --- title: Webhook events for the GitHub Marketplace API intro: 'A {% data variables.product.prodname_marketplace %} app receives information about changes to a user''s plan from the Marketplace purchase event webhook. A Marketplace purchase event is triggered when a user purchases, cancels, or changes their payment plan. For details on how to respond to each of these types of events, see "[Billing flows](/marketplace/integrating-with-the-github-marketplace-api/#billing-flows)."' intro: 'A {% data variables.product.prodname_marketplace %} app receives information about changes to a user''s plan from the Marketplace purchase event webhook. A Marketplace purchase event is triggered when a user purchases, cancels, or changes their payment plan.' redirect_from: - /apps/marketplace/setting-up-github-marketplace-webhooks/about-webhook-payloads-for-a-github-marketplace-listing/ - /apps/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/ 4 content/developers/webhooks-and-events/webhook-events-and-payloads.md @@ -445,7 +445,7 @@ Key | Type | Description #### Webhook payload object {% data reusables.webhooks.installation_properties %} {% data reusables.webhooks.app_desc %} {% data reusables.webhooks.app_always_desc %} {% data reusables.webhooks.sender_desc %} #### Webhook payload example @@ -469,7 +469,7 @@ Key | Type | Description #### Webhook payload object {% data reusables.webhooks.installation_repositories_properties %} {% data reusables.webhooks.app_desc %} {% data reusables.webhooks.app_always_desc %} {% data reusables.webhooks.sender_desc %} #### Webhook payload example 54 ...ssions/collaborating-with-your-community-using-discussions/about-discussions.md @@ -0,0 +1,54 @@ --- title: About discussions intro: Use discussions to ask and answer questions, share information, make announcements, and conduct or participate in a conversation about a project on {% data variables.product.product_name %}. versions: free-pro-team: '*' --- {% data reusables.discussions.beta %} ### About discussions With {% data variables.product.prodname_discussions %}, the community for your project can create and participate in conversations within the project's repository. Discussions empower a project's maintainers, contributors, and visitors to gather and accomplish the following goals in a central location, without third-party tools. - Share announcements and information, gather feedback, plan, and make decisions - Ask questions, discuss and answer the questions, and mark the discussions as answered - Foster an inviting atmosphere for visitors and contributors to discuss goals, development, administration, and workflows  You don't need to close a discussion like you close an issue or a pull request. If a repository administrator or project maintainer enables discussions for a repository, anyone who visits the repository can create and participate in discussions for the repository. Repository administrators and project maintainers can manage discussions and discussion categories in a repository, and pin discussions to increase the visibility of the discussion. Moderators and collaborators can mark comments as answers, lock discussions, and convert issues to discussions. For more information, see "[Repository permission levels for an organization](/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization)." For more information about management of discussions for your repository, see "[Managing discussions in your repository](/discussions/managing-discussions-for-your-community/managing-discussions-in-your-repository)." ### About categories and formats for discussions {% data reusables.discussions.you-can-categorize-discussions %} {% data reusables.discussions.about-categories-and-formats %} {% data reusables.discussions.repository-category-limit %} For discussions with a question/answer format, an individual comment within the discussion can be marked as the discussion's answer. {% data reusables.discussions.github-recognizes-members %} For more information, see "[Managing categories for discussions in your repository](/discussions/managing-discussions-for-your-community/managing-categories-for-discussions-in-your-repository)." ### Best practices for discussions As a community member or maintainer, start a discussion to ask a question or discuss information that affects the community. For more information, see "[Collaborating with maintainers using discussions](/discussions/collaborating-with-your-community-using-discussions/collaborating-with-maintainers-using-discussions)." Participate in a discussion to ask and answer questions, provide feedback, and engage with the project's community. For more information, see "[Participating in a discussion](/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion)." You can spotlight discussions that contain important, useful, or exemplary conversations among members in the community. For more information, see "[Managing discussions in your repository](/discussions/managing-discussions-for-your-community/managing-discussions-in-your-repository#pinning-a-discussion)." {% data reusables.discussions.you-can-convert-an-issue %} For more information, see "[Moderating discussions in your repository](/discussions/managing-discussions-for-your-community/moderating-discussions#converting-an-issue-to-a-discussion)." ### Sharing feedback You can share your feedback about {% data variables.product.prodname_discussions %} with {% data variables.product.company_short %}. To join the conversation, see [`github/feedback`](https://github.com/github/feedback/discussions?discussions_q=category%3A%22Discussions+Feedback%22). ### Further reading - "[About writing and formatting on {% data variables.product.prodname_dotcom %}](/github/writing-on-github/about-writing-and-formatting-on-github)" - "[Searching discussions](/github/searching-for-information-on-github/searching-discussions)" - "[About notifications](/github/managing-subscriptions-and-notifications-on-github/about-notifications)" - "[Moderating comments and conversations](/github/building-a-strong-community/moderating-comments-and-conversations)" - "[Maintaining your safety on {% data variables.product.prodname_dotcom %}](/github/building-a-strong-community/maintaining-your-safety-on-github)" 50 ...community-using-discussions/collaborating-with-maintainers-using-discussions.md @@ -0,0 +1,50 @@ --- title: Collaborating with maintainers using discussions shortTitle: Collaborating with maintainers intro: You can contribute to the goals, plans, health, and community for a project on {% data variables.product.product_name %} by communicating with the maintainers of the project in a discussion. permissions: People with read permissions to a repository can start and participate in discussions in the repository. versions: free-pro-team: '*' --- {% data reusables.discussions.beta %} ### About collaboration with maintainers using discussions {% data reusables.discussions.about-discussions %} If you use or contribute to a project, you can start a discussion to make suggestions and engage with maintainers and community members about your plans, questions, ideas, and feedback. For more information, see "[About discussions](/discussions/collaborating-with-your-community-using-discussions/about-discussions)." {% data reusables.discussions.about-categories-and-formats %} Repository administrators and project maintainers can delete a discussion. For more information, see "[Managing discussions in your repository](/discussions/managing-discussions-for-your-community/managing-discussions-in-your-repository#deleting-a-discussion)." {% data reusables.discussions.github-recognizes-members %} These members appear in a list of the most helpful contributors to the project's discussions. As your project grows, you can grant higher access permissions to active members of your community. For more information, see "[Granting higher permissions to top contributors](/discussions/guides/granting-higher-permissions-to-top-contributors)"  For more information about participation in discussions, see "[Participating in a discussion](/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion)." ### Prerequisites To collaborate with maintainers using discussions, a repository administrator or project maintainer must enable discussions for the repository. For more information, see "[Enabling or disabling discussions for a repository](/github/administering-a-repository/enabling-or-disabling-github-discussions-for-a-repository)." ### Starting a discussion {% data reusables.discussions.starting-a-discussion %} ### Filtering the list of discussions You can search for discussions and filter the list of discussions in a repository. For more information, see "[Searching discussions](/github/searching-for-information-on-github/searching-discussions)." {% data reusables.repositories.navigate-to-repo %} {% data reusables.discussions.discussions-tab %} 1. In the **Search all discussions** field, type a search query. Optionally, to the right of the search field, click a button to further filter the results.  1. In the list of discussions, click the discussion you want to view.  ### Converting an issue to a discussion {% data reusables.discussions.you-can-convert-an-issue %} For more information, see "[Moderating discussions in your repository](/discussions/managing-discussions-for-your-community/moderating-discussions#converting-an-issue-to-a-discussion#converting-an-issue-to-a-discussion)." ### Further reading - "[About writing and formatting on {% data variables.product.prodname_dotcom %}](/github/writing-on-github/about-writing-and-formatting-on-github)" - "[Maintaining your safety on {% data variables.product.prodname_dotcom %}](/github/building-a-strong-community/maintaining-your-safety-on-github)" 14 content/discussions/collaborating-with-your-community-using-discussions/index.md @@ -0,0 +1,14 @@ --- title: Collaborating with your community using discussions shortTitle: Collaborating using discussions intro: Gather and discuss your project with community members and other maintainers. versions: free-pro-team: '*' --- {% data reusables.discussions.beta %} {% link_in_list /about-discussions %} {% link_in_list /participating-in-a-discussion %} {% link_in_list /collaborating-with-maintainers-using-discussions %} 31 ...borating-with-your-community-using-discussions/participating-in-a-discussion.md @@ -0,0 +1,31 @@ --- title: Participating in a discussion intro: You can converse with the community and maintainers in a forum within the repository for a project on {% data variables.product.product_name %}. permissions: People with read permissions to a repository can participate in discussions in the repository. versions: free-pro-team: '*' --- {% data reusables.discussions.beta %} ### About participation in a discussion {% data reusables.discussions.about-discussions %} For more information, see "[About discussions](/discussions/collaborating-with-your-community-using-discussions/about-discussions)." In addition to starting or viewing a discussion, you can comment in response to the original comment from the author of the discussion. You can also create a comment thread by replying to an individual comment that another community member made within the discussion, and react to comments with emoji. For more information about reactions, see "[About conversations on {% data variables.product.prodname_dotcom %}](/github/collaborating-with-issues-and-pull-requests/about-conversations-on-github#reacting-to-ideas-in-comments)." You can block users and report disruptive content to maintain a safe and pleasant environment for yourself on {% data variables.product.product_name %}. For more information, see "[Maintaining your safety on {% data variables.product.prodname_dotcom %}](/github/building-a-strong-community/maintaining-your-safety-on-github)." ### Prerequisites Discussions must be enabled for the repository for you to participate in a discussion in the repository. For more information, see "[Enabling or disabling discussions for a repository](/github/administering-a-repository/enabling-or-disabling-github-discussions-for-a-repository)." ### Creating a discussion {% data reusables.discussions.starting-a-discussion %} ### Marking a comment as an answer Discussion authors and users with the triage role or greater for a repository can mark a comment as the answer to a discussion in the repository. {% data reusables.discussions.marking-a-comment-as-an-answer %} 49 content/discussions/guides/best-practices-for-community-conversations-on-github.md @@ -0,0 +1,49 @@ --- title: Best practices for community conversations on GitHub shortTitle: Best practices for community conversations intro: 'You can use discussions to brainstorm with your team, and eventually move the conversation to a discussion when you are ready to scope out the work.' versions: free-pro-team: '*' --- {% data reusables.discussions.beta %} ### Community conversations in {% data variables.product.prodname_discussions %} Since {% data variables.product.prodname_discussions %} is an open forum, there is an opportunity to bring non-code collaboration into a project's repository and gather diverse feedback and ideas more quickly. You can help drive a productive conversation by: - Asking pointed questions and follow-up questions to garner specific feedback - Capture a diverse experience and distill it down to main points - Open an issue to take action based on the conversation, where applicable For more information about opening an issue and cross-referencing a discussion, see "[Opening an issue from a comment](/github/managing-your-work-on-github/opening-an-issue-from-a-comment)." ### Learning about conversations on GitHub You can create and participate in discussions, issues, and pull requests, depending on the type of conversation you'd like to have. You can use {% data variables.product.prodname_discussions %} to discuss big picture ideas, brainstorm, and spike out a project's specific details before committing it to an issue, which can then be scoped. Discussions are useful for teams if: - You are in the discovery phase of a project and are still learning which director your team wants to go in - You want to collect feedback from a wider community about a project - You want to keep bug fixes, feature requests, and general conversations separate Issues are useful for discussing specific details of a project such as bug reports and planned improvements. For more information, see "[About issues](/articles/about-issues)." Pull requests allow you to comment directly on proposed changes. For more information, see "[About pull requests](/articles/about-pull-requests)" and "[Commenting on a pull request](/articles/commenting-on-a-pull-request)." {% data reusables.organizations.team-discussions-purpose %} For more information, see "[About team discussions](/articles/about-team-discussions)." ### Following contributing guidelines Before you open a discussion, check to see if the repository has contributing guidelines. The CONTRIBUTING file includes information about how the repository maintainer would like you to contribute ideas to the project. For more information, see "[Setting up your project for healthy contributions](/github/building-a-strong-community/setting-up-your-project-for-healthy-contributions)." ### Next steps To continue learning about {% data variables.product.prodname_discussions %} and quickly create a discussion for your community, see "[Quickstart for {% data variables.product.prodname_discussions %}](/discussions/quickstart)." ### Further reading - "[Setting up your project for healthy contributions](/articles/setting-up-your-project-for-healthy-contributions)" - "[Using templates to encourage useful issues and pull requests](/github/building-a-strong-community/using-templates-to-encourage-useful-issues-and-pull-requests)" - "[Moderating comments and conversations](/articles/moderating-comments-and-conversations)" - "[Writing on {% data variables.product.prodname_dotcom %}](/articles/writing-on-github)" 21 content/discussions/guides/finding-discussions-across-multiple-repositories.md @@ -0,0 +1,21 @@ --- title: Finding discussions across multiple repositories intro: 'You can easily access every discussion you''ve created or participated in across multiple repositories.' versions: free-pro-team: '*' --- {% data reusables.discussions.beta %} ### Finding discussions 1. Navigate to {% data variables.product.prodname_dotcom_the_website %}. 1. In the top-right corner of {% data variables.product.prodname_dotcom_the_website %}, click your profile photo, then click **Your enterprises**.  1. Toggle between **Created** and **Commented** to see the discussions you've created or participated in. ### Further reading - "[Searching discussions](/github/searching-for-information-on-github/searching-discussions)" - "[About discussions](/discussions/collaborating-with-your-community-using-discussions/about-discussions)" - "[Managing discussions for your community](/discussions/managing-discussions-for-your-community)" 32 content/discussions/guides/granting-higher-permissions-to-top-contributors.md @@ -0,0 +1,32 @@ --- title: Granting higher permissions to top contributors intro: 'Repository administrators can promote any community member to a moderator and maintainer.' versions: free-pro-team: '*' --- {% data reusables.discussions.beta %} ### Introduction The most helpful contributors for the past 30 days are highlighted on the {% data variables.product.prodname_discussions %} dashboard, based on how many comments were marked as answers by other community members. Helpful contributors can help drive a healthy community and moderate and guide the community space in addition to maintainers. ### Step 1: Audit your discussions top contributors {% data reusables.repositories.navigate-to-repo %} {% data reusables.discussions.discussions-tab %} 1. Compare the list of contributors with their access permissions to see who qualifies to moderate the discussion. ### Step 2: Review permission levels for discussions People with triage permissions for a repository can help moderate a project's discussions by marking comments as answers, locking discussions that are not longer useful or are damaging to the community, and converting issues to discussions when an idea is still in the early stages of development. For more information, see "[Moderating discussions](/discussions/managing-discussions-for-your-community/moderating-discussions)." For more information about repository permission levels and {% data variables.product.prodname_discussions %}, see "[Repository permissions levels for an organization](/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization)." ### Step 3: Change permissions levels for top contributors You can change a contributor's permission levels to give them more access to the tooling they need to moderate GitHub Discussions. To change a person's or team's permission levels, see "[Managing teams and people with access to your repository](/github/administering-a-repository/managing-teams-and-people-with-access-to-your-repository)." ### Step 4: Notify community members of elevated access When you change a collaborators permission level, they will receive a notification for the change. 29 content/discussions/guides/index.md @@ -0,0 +1,29 @@ --- title: Discussions guides shortTitle: Guides intro: 'Discover pathways to get started or learn best practices for participating or monitoring your community''s discussions.' versions: free-pro-team: '*' --- {% data reusables.discussions.beta %} ### Getting started with discussions {% link_in_list /about-discussions %} {% link_in_list /best-practices-for-community-conversations-on-github %} {% link_in_list /finding-discussions-across-multiple-repositories %} <!-- {% link_in_list /managing-notifications-for-discussions %} --> ### Administering discussions {% link_in_list /granting-higher-permissions-to-top-contributors %} <!--<!-- Commenting out what is only nice to have for discussions release {% link_in_list /updating-your-contributing-guidelines-with-discussions %} --> <!-- ### Discussions and open source projects {% link_in_list /collaborating-on-open-source-projects-in-discussions %} {% link_in_list /welcoming-contributions-to-your-communitys-discussions %} --> 55 content/discussions/index.md @@ -0,0 +1,55 @@ --- title: GitHub Discussions Documentation beta_product: true shortTitle: GitHub Discussions intro: '{% data variables.product.prodname_discussions %} is a collaborative communication forum for the community around an open source project. Community members can ask and answer questions, share updates, have open-ended conversations, and follow along on decisions affecting the community''s way of working.' introLinks: quickstart: /discussions/quickstart featuredLinks: guides: - /discussions/collaborating-with-your-community-using-discussions/about-discussions - /discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion - /discussions/managing-discussions-for-your-community/moderating-discussions gettingStarted: - /discussions/quickstart guideCards: - /discussions/collaborating-with-your-community-using-discussions/about-discussions - /discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion - /discussions/managing-discussions-for-your-community/moderating-discussions popular: - /discussions/guides/granting-higher-permissions-to-top-contributors - /discussions/guides/best-practices-for-community-conversations-on-github - /discussions/guides/finding-discussions-across-multiple-repositories - /discussions/collaborating-with-your-community-using-discussions/collaborating-with-maintainers-using-discussions - /discussions/managing-discussions-for-your-community/managing-categories-for-discussions-in-your-repository product_video: https://www.youtube-nocookie.com/embed/DbTWBP3_RbM layout: product-landing versions: free-pro-team: '*' --- <!-- {% link_with_intro /quickstart %} --> <!-- {% link_with_intro /discussions-guides %} --> <!-- {% link_with_intro /collaborating-with-your-community-using-discussions %} --> <!-- {% link_with_intro /managing-discussions-for-your-community %} --> <!-- Community examples --> {% assign discussionsCommunityExamples = site.data.variables.discussions_community_examples %} {% if discussionsCommunityExamples %} <div class="my-6 pt-6"> <h2 class="mb-2 font-mktg h1">Communities using discussions</h2> <div class="d-flex flex-wrap gutter"> {% render 'discussions-community-card' for discussionsCommunityExamples as example %} </div> {% if discussionsCommunityExamples.length > 6 %} <button class="js-filter-card-show-more btn btn-outline float-right">Show more {% octicon "arrow-right" %}</button> {% endif %} <div class="js-filter-card-no-results d-none py-4 text-center text-gray font-mktg"> <div class="mb-3">{% octicon "search" width="24" %}</div> <h3 class="text-normal">Sorry, there is no result for <strong class="js-filter-card-value"></strong></h3> <p class="my-3 f4">It looks like we don't have an example that fits your filter.<br>Try another filter or add your code example</p> <a href="https://github.com/github/docs/blob/main/data/variables/discussions_community_examples.yml">Add your community {% octicon "arrow-right" %}</a> </div> </div> {% endif %} 13 content/discussions/managing-discussions-for-your-community/index.md @@ -0,0 +1,13 @@ --- title: Managing discussions for your community shortTitle: Managing discussions intro: 'You can enable and configure discussions for your repository, and you can use tools on {% data variables.product.product_name %} to moderate conversations among community members.' versions: free-pro-team: '*' --- {% data reusables.discussions.beta %} {% link_in_list /managing-discussions-in-your-repository %} {% link_in_list /managing-categories-for-discussions-in-your-repository %} {% link_in_list /moderating-discussions %} 64 ...ns-for-your-community/managing-categories-for-discussions-in-your-repository.md @@ -0,0 +1,64 @@ --- title: Managing categories for discussions in your repository intro: You can categorize the discussions in your repository to organize conversations for your community members, and you can choose a format for each category. permissions: Repository administrators and people with write or greater access to a repository can enable discussions in the repository. versions: free-pro-team: '*' --- {% data reusables.discussions.beta %} ### About categories for discussions {% data reusables.discussions.about-discussions %} {% data reusables.discussions.about-categories-and-formats %} Each category must have a unique name and emoji pairing, and can be accompanied by a detailed description stating its purpose. Categories help maintainers organize how conversations are filed and are customizable to help distinguish categories that are Q&A or more open-ended conversations.{% data reusables.discussions.repository-category-limit %} For more information, see "[About discussions](/discussions/collaborating-with-your-community-using-discussions/about-discussions#about-categories-and-formats-for-discussions)." ### Default categories | Category | Purpose | Type | | :- | :- | :- | | #️⃣ General | Anything and everything relevant to the project | Open-ended discussion | |💡Ideas | Ideas to change or improve the project | Open-ended discussion | | 🙏 Q&A | Questions for the community to answer, with a question/answer format | Question and Answer | | 🙌 Show and tell | Creations, experiments, or tests relevant to the project | Open-ended discussion | ### Creating a category {% data reusables.repositories.navigate-to-repo %} {% data reusables.discussions.discussions-tab %} {% data reusables.discussions.edit-categories %} 1. Click **New category**.  1. Edit the emoji, title, description, and discussion format for the category. For more information about discussion formats, see "[About discussions](/discussions/collaborating-with-your-community-using-discussions/about-discussions#about-categories-and-formats-for-discussions)."  1. Click **Create**.  ### Editing a category You can edit a category to change the category's emoji, title, description, and discussion format. {% data reusables.repositories.navigate-to-repo %} {% data reusables.discussions.discussions-tab %} 1. To the right of a category in the list, click {% octicon "pencil" aria-label="The pencil icon" %}.  1. {% data reusables.discussions.edit-category-details %}  1. Click **Save changes**.  ### Deleting a category When you delete a category, {% data variables.product.product_name %} will move all discussions in the deleted category to an existing category that you choose. {% data reusables.repositories.navigate-to-repo %} {% data reusables.discussions.discussions-tab %} 1. To the right of a category in the list, click {% octicon "trash" aria-label="The trash icon" %}.  1. Use the drop-down menu, and choose a new category for any discussions in the category you're deleting.  1. Click **Delete & Move**.  108 ...aging-discussions-for-your-community/managing-discussions-in-your-repository.md @@ -0,0 +1,108 @@ --- title: Managing discussions in your repository intro: You can categorize, spotlight, transfer, or delete the discussions in a repository. permissions: Repository administrators and people with write or greater access to a repository can manage discussions in the repository. versions: free-pro-team: '*' --- {% data reusables.discussions.beta %} ### About management of discussions {% data reusables.discussions.about-discussions %} For more information about discussions, see "[About discussions](/discussions/collaborating-with-your-community-using-discussions/about-discussions)." Organization owners can choose the permissions required to create a discussion for repositories owned by the organization. For more information, see "[Managing discussion creation for repositories in your organization](/github/setting-up-and-managing-organizations-and-teams/managing-discussion-creation-for-repositories-in-your-organization)." As a discussions maintainer, you can create community resources to encourage discussions that are aligned with the overall project goal and maintain a friendly open forum for collaborators. Creating a code of conduct or contribution guidelines for collaborators to follow will help facilitate a collaborative and productive forum. For more information on creating community resources, see "[Adding a code of conduct to your project](/github/building-a-strong-community/adding-a-code-of-conduct-to-your-project)," and "[Setting guidelines for repository contributors](/github/building-a-strong-community/setting-guidelines-for-repository-contributors)." For more information on facilitating a healthy discussion, see "[Moderating comments and conversations](/github/building-a-strong-community/moderating-comments-and-conversations)." ### Prerequisites To manage discussions in a repository, discussions must be enabled for the repository. For more information, see "[Enabling or disabling discussions for a repository](/github/administering-a-repository/enabling-or-disabling-github-discussions-for-a-repository)." ### Changing the category for a discussion You can categorize discussions to help community members find related discussions. For more information, see "[Managing categories for discussions in your repository](/discussions/managing-discussions-for-your-community/managing-categories-for-discussions-in-your-repository)" article. You can also move a discussion to a different category. {% data reusables.repositories.navigate-to-repo %} {% data reusables.discussions.discussions-tab %} {% data reusables.discussions.click-discussion-in-list %} 1. In the right sidebar, click {% octicon "pencil" aria-label="The pencil icon" %} **Edit pinned discussion**.  ### Pinning a discussion You can pin up to four important discussions above the list of discussions for the repository. {% data reusables.repositories.navigate-to-repo %} {% data reusables.discussions.discussions-tab %} {% data reusables.discussions.click-discussion-in-list %} 1. In the right sidebar, click {% octicon "pin" aria-label="The pin icon" %} **Pin discussion**.  1. Optionally, customize the look of the pinned discussion.  1. Click **Pin discussion**.  ### Editing a pinned discussion Editing a pinned discussion will not change the discussion's category. For more information, see "[Managing categories for discussions in your repository](/discussions/managing-discussions-for-your-community/managing-categories-for-discussions-in-your-repository)." {% data reusables.repositories.navigate-to-repo %} {% data reusables.discussions.discussions-tab %} {% data reusables.discussions.click-discussion-in-list %} 1. In the right sidebar, click {% octicon "pencil" aria-label="The pencil icon" %} **Edit pinned discussion**.  1. Customize the look of the pinned discussion.  1. Click **Pin discussion**.  ### Unpinning a discussion {% data reusables.repositories.navigate-to-repo %} {% data reusables.discussions.discussions-tab %} {% data reusables.discussions.click-discussion-in-list %} 1. In the right sidebar, click {% octicon "pin" aria-label="The pin icon" %} **Unpin discussion**.  1. Read the warning, then click **Unpin discussion**.  ### Transferring a discussion To transfer a discussion, you must have permissions to create discussions in the repository where you want to transfer the discussion. {% data reusables.repositories.navigate-to-repo %} {% data reusables.discussions.discussions-tab %} {% data reusables.discussions.click-discussion-in-list %} 1. In the right sidebar, click {% octicon "arrow-right" aria-label="The right arrow icon" %} **Transfer discussion**.  1. Select the **Choose a repository** drop-down, and click the repository you want to transfer the discussion to.  1. Click **Transfer discussion**.  ### Deleting a discussion {% data reusables.repositories.navigate-to-repo %} {% data reusables.discussions.discussions-tab %} {% data reusables.discussions.click-discussion-in-list %} 1. In the right sidebar, click {% octicon "trash" aria-label="The trash arrow icon" %} **Delete discussion**.  1. Read the warning, then click **Delete this discussion**.  ### Converting issues based on labels You can convert all issues with the same label to discussions in bulk. Future issues with this label will also automatically convert to the discussion and category you configure. {% data reusables.repositories.navigate-to-repo %} {% data reusables.repositories.sidebar-issues %} {% data reusables.project-management.labels %} 1. Next to the label you want to convert to issues, click **Convert issues**. 1. Select the **Choose a category** drop-down menu, and click a category for your discussion. 1. Click **I understand, convert this issue to a discussion**. 40 ...t/discussions/managing-discussions-for-your-community/moderating-discussions.md @@ -0,0 +1,40 @@ --- title: Moderating discussions intro: 'You can promote healthy collaboration by marking comments as answers, locking or unlocking discussions, and converting issues to discussions. and editing or deleting comments, discussions, and categories that don''t align with your community''s code of conduct to discussions.' permissions: People with triage access to a repository can moderate discussions in the repository. versions: free-pro-team: '*' --- {% data reusables.discussions.beta %} ### About moderating discussions {% data reusables.discussions.about-discussions %} If you have triage permissions for a repository, you can help moderate a project's discussions by marking comments as answers, locking discussions that are not longer useful or are damaging to the community, and converting issues to discussions when an idea is still in the early stages of development. ### Marking a comment as an answer {% data reusables.discussions.marking-a-comment-as-an-answer %} ### Locking discussions It's appropriate to lock a conversation when the entire conversation is not constructive or violates your community's code of conduct or {% data variables.product.prodname_dotcom %}'s [Community Guidelines](/github/site-policy/github-community-guidelines). You can also lock a conversation to prevent comments on a discussion you want to use as an announcement to the community. When you lock a conversation, people with write access to the repository will still be able to comment on the discussion. {% data reusables.repositories.navigate-to-repo %} {% data reusables.discussions.discussions-tab %} 1. In the list of discussions, click the discussion you want to lock.  1. In the right margin of a discussion, click **Lock conversation**. 1. Read the information about locking conversations and click **Lock conversation on this discussion**. 1. When you're ready to unlock the conversation, click **Unlock conversation**, then click **Unlock conversation on this discussion**. ### Converting an issue to a discussion When you convert an issue to a discussion, the discussion is automatically created using the content from the issue. People with write access to a repository can bulk convert issues based on labels. For more information, see "[Managing discussions in your repository](/discussions/managing-discussions-for-your-community/managing-discussions-in-your-repository)." {% data reusables.repositories.navigate-to-repo %} {% data reusables.repositories.sidebar-issues %} 1. In the list of issues, click the issue you'd like to convert. 1. In the right margin of an issue, click **Convert to discussion**. 1. Select the **Choose a category** drop-down menu, and click a category for your discussion. 1. Click **I understand, convert this issue to a discussion**. 62 content/discussions/quickstart.md @@ -0,0 +1,62 @@ --- title: Quickstart for GitHub Discussions intro: 'Enable {% data variables.product.prodname_discussions %} on an existing repository and start conversations with your community.' allowTitleToDifferFromFilename: true versions: free-pro-team: '*' --- {% data reusables.discussions.beta %} ### Introduction {% data variables.product.prodname_discussions %} is a collaborative communication forum for the community around an open source project. Discussions are for conversations that need to be transparent and accessible but do not need to be tracked on a project board and are not related to code, unlike issues. Discussions enable fluid, open conversation in a public forum. Discussions give a space for more collaborative conversations by connecting and giving a more centralized area to connect and find information. ### Enabling {% data variables.product.prodname_discussions %} on your repository Repository owners and people with write access can enable {% data variables.product.prodname_discussions %} for a community on their public repositories. When you first enable a {% data variables.product.prodname_discussions %}, you will be invited to configure a welcome post. {% data reusables.repositories.navigate-to-repo %} 1. Under your repository name, click {% octicon "gear" aria-label="The gear icon" %} **Settings**.  1. Under "Features", click **Set up discussions**.  1. Under "Start a new discussion," edit the template to align with the resources and tone you want to set for your community. 1. Click **Start discussion**.  ### Welcoming contributions to your discussions You can welcome your community and introduce a new way to communicate in a repository by creating a welcome post and pin the post to your {% data variables.product.prodname_discussions %} page. Pinning and locking discussions helps people know that a post is meant as an announcement. You can use announcements as a way to link people to more resources and offer guidance for opening discussions in your community. For more information about pinning a discussion, see "[Managing discussions in your repository](/discussions/managing-discussions-for-your-community/managing-discussions-in-your-repository#pinning-a-discussion)." ### Setting up community guidelines for contributors You can set contributing guidelines to encourage collaborators to have meaningful, useful conversations that are relevant to the repository. You can also update the repository's README to communicate expectations on when collaborators should open an issue or discussion. For more information about providing guidelines for your project, see "[Adding a code of conduct to your project](/github/building-a-strong-community/adding-a-code-of-conduct-to-your-project)" and "[Setting up your project for healthy contributions](/github/building-a-strong-community/setting-up-your-project-for-healthy-contributions)." ### Creating a new discussion Anyone with access to a repository can create a discussion. {% data reusables.discussions.starting-a-discussion %} ### Organizing discussions into relevant categories Repository owners and people with write access can create new categories to keep discussions organized. Collaborators participating and creating new discussions can group discussions into the most relevant existing categories. Discussions can also be recategorized after they are created. For more information, see "[Managing categories for discussions in your repository](/discussions/managing-discussions-for-your-community/managing-categories-for-discussions-in-your-repository)" ### Promoting healthy conversations People with write permissions for a repository can help surface important conversations by pinning discussions, deleting discussions that are no longer useful or are damaging to the community, and transferring discussions to more relevant repositories owned by the organization. For more information, see "[Managing discussions in your repository](/discussions/managing-discussions-for-your-community/managing-discussions-in-your-repository)." People with triage permissions for a repository can help moderate a project's discussions by marking comments as answers, locking discussions that are not longer useful or are damaging to the community, and converting issues to discussions when an idea is still in the early stages of development. For more information, see "[Moderating discussions](/discussions/managing-discussions-for-your-community/moderating-discussions)." ### Next steps Once there is a clear path to scope work out and move an idea from concept to reality, you can create an issue and start tracking your progress. For more information on creating an issue from a discussion, see "[Moderating discussions](/discussions/managing-discussions-for-your-community/moderating-discussions)." 45 content/education/guides.md @@ -0,0 +1,45 @@ --- title: Guides for GitHub Education intro: 'These guides for {% data variables.product.prodname_education %} help you teach and learn both {% data variables.product.product_name %} and software development.' allowTitleToDifferFromFilename: true versions: free-pro-team: '*' --- ### Get started with {% data variables.product.product_name %} Teachers, students, and researchers can use tools from {% data variables.product.product_name %} to enrich a software development curriculum and develop real-world collaboration skills. - [Sign up for a new {% data variables.product.prodname_dotcom %} account](/github/getting-started-with-github/signing-up-for-a-new-github-account) - [Git and {% data variables.product.prodname_dotcom %} quickstart ](/github/getting-started-with-github/quickstart) - [Apply for an educator or researcher discount](/education/teach-and-learn-with-github-education/apply-for-an-educator-or-researcher-discount) - [Apply for a student developer pack](/education/teach-and-learn-with-github-education/apply-for-a-student-developer-pack) ### Run a software development course with {% data variables.product.company_short %} Administer a classroom, assign and review work from your students, and teach the new generation of software developers with {% data variables.product.prodname_classroom %}. - [Basics of setting up {% data variables.product.prodname_classroom %} ](/education/manage-coursework-with-github-classroom/basics-of-setting-up-github-classroom) - [Manage classrooms](/education/manage-coursework-with-github-classroom/manage-classrooms) - [Create an individual assignment](/education/manage-coursework-with-github-classroom/create-an-individual-assignment) - [Create a group assignment](/education/manage-coursework-with-github-classroom/create-a-group-assignment) - [Create an assignment from a template repository](/education/manage-coursework-with-github-classroom/create-an-assignment-from-a-template-repository) - [Leave feedback with pull requests](/education/manage-coursework-with-github-classroom/leave-feedback-with-pull-requests) - [Use autograding](/education/manage-coursework-with-github-classroom/use-autograding) ### Learn to develop software Incorporate {% data variables.product.prodname_dotcom %} into your education, and use the same tools as the professionals. - [Git and {% data variables.product.prodname_dotcom %} learning resources](/github/getting-started-with-github/git-and-github-learning-resources) - [Use {% data variables.product.prodname_dotcom %} for your schoolwork](/education/teach-and-learn-with-github-education/use-github-for-your-schoolwork) - [Try {% data variables.product.prodname_desktop %}](/desktop) - [Try {% data variables.product.prodname_cli %}](/github/getting-started-with-github/github-cli) ### Contribute to the community Participate in the community, get training from {% data variables.product.company_short %}, and learn or teach new skills. - [{% data variables.product.prodname_education_community %}](https://education.github.community) - [About Campus Experts](/education/teach-and-learn-with-github-education/about-campus-experts) - [About Campus Advisors](/education/teach-and-learn-with-github-education/about-campus-advisors) 43 content/education/index.md @@ -0,0 +1,43 @@ --- title: GitHub Education Documentation shortTitle: Education intro: "{% data variables.product.prodname_education %} helps you teach or learn software development with the tools and support of {% data variables.product.company_short %}'s platform and community." introLinks: quickstart: /education/quickstart featuredLinks: guides: - /education/teach-and-learn-with-github-education/apply-for-a-student-developer-pack - /education/teach-and-learn-with-github-education/apply-for-an-educator-or-researcher-discount - /education/teach-and-learn-with-github-education/use-github-at-your-educational-institution guideCards: - /github/getting-started-with-github/signing-up-for-a-new-github-account - /github/getting-started-with-github/git-and-github-learning-resources - /education/manage-coursework-with-github-classroom/basics-of-setting-up-github-classroom popular: - /education/teach-and-learn-with-github-education/use-github-for-your-schoolwork - /education/teach-and-learn-with-github-education/use-github-in-your-classroom-and-research - /desktop - /github/getting-started-with-github/github-cli - /education/manage-coursework-with-github-classroom/teach-with-github-classroom changelog: - title: 'Try something new at Local Hack Day: Learn' date: '2020-10-15' href: https://github.blog/2020-10-15-try-something-new-at-local-hack-day-learn/ - title: 'Remote Education: Creating community through shared experiences' date: '2020-09-24' href: https://github.blog/2020-09-24-remote-education-creating-community-through-shared-experiences/ - title: 'Remote Education: A series of best practices for online campus communities' date: '2020-09-10' href: https://github.blog/2020-09-10-remote-education-a-series-of-best-practices-for-online-campus-communities/ - title: Welcome to the inaugural class of MLH Fellows date: '2020-06-24' href: https://github.blog/2020-06-24-welcome-to-the-inaugural-class-of-mlh-fellows/ layout: product-landing versions: free-pro-team: '*' --- <!-- {% link_with_intro /teach-and-learn-with-github-education %} --> <!-- {% link_with_intro /manage-coursework-with-github-classroom %} --> 31 ...work-with-github-classroom/about-using-makecode-arcade-with-github-classroom.md @@ -0,0 +1,31 @@ --- title: About using MakeCode Arcade with GitHub Classroom shortTitle: About using MakeCode Arcade intro: You can configure MakeCode Arcade as the online IDE for assignments in {% data variables.product.prodname_classroom %}. versions: free-pro-team: '*' redirect_from: - /education/manage-coursework-with-github-classroom/student-experience-makecode --- ### About MakeCode Arcade MakeCode Arcade is an online integrated development environment (IDE) for developing retro arcade games using drag-and-drop block programming and JavaScript. Students can write, edit, run, test, and debug code in a browser with MakeCode Arcade. For more information about online IDEs and {% data variables.product.prodname_classroom %}, see "[Integrate {% data variables.product.prodname_classroom %} with an online IDE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-online-ide)." {% data reusables.classroom.readme-contains-button-for-online-ide %} The first time the student clicks the button to visit MakeCode Arcade, the student must sign into MakeCode Arcade with {% data variables.product.product_name %} credentials. After signing in, the student will have access to a development environment containing the code from the assignment repository, fully configured on MakeCode Arcade. For more information about working on MakeCode Arcade, see the [MakeCode Arcade Tour](https://arcade.makecode.com/ide-tour) and [documentation](https://arcade.makecode.com/docs) on the MakeCode Arcade website. MakeCode Arcade does not support multiplayer-editing for group assignments. Instead, students can collaborate with Git and {% data variables.product.product_name %} features like branches and pull requests. ### About submission of assignments with MakeCode Arcade By default, MakeCode Arcade is configured to push to the assignment repository on {% data variables.product.product_location %}. After making progress on an assignment with MakeCode Arcade, students should push changes to {% data variables.product.product_location %} using the {% octicon "mark-github" aria-label="The GitHub mark" %}{% octicon "arrow-up" aria-label="The up arrow icon" %} button at the bottom of the screen.  ### Further reading - "[About READMEs](/github/creating-cloning-and-archiving-repositories/about-readmes)" 33 ...ge-coursework-with-github-classroom/about-using-replit-with-github-classroom.md @@ -0,0 +1,33 @@ --- title: About using Repl.it with GitHub Classroom shortTitle: About using Repl.it intro: You can configure Repl.it as the online integrated development environment (IDE) for assignments in {% data variables.product.prodname_classroom %}. versions: free-pro-team: '*' redirect_from: - /education/manage-coursework-with-github-classroom/student-experience-replit --- ### About Repl.it Repl.it is an online integrated development environment (IDE) that supports multiple programming languages. Students can write, edit, run, test, and debug code in a browser with Repl.it. For more information about online IDEs and {% data variables.product.prodname_classroom %}, see "[Integrate {% data variables.product.prodname_classroom %} with an online IDE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-online-ide)." {% data reusables.classroom.readme-contains-button-for-online-ide %} The first time the student clicks the button to visit Repl.it, the student must sign into Repl.it with {% data variables.product.product_name %} credentials. After signing in, the student will have access to a development environment containing the code from the assignment repository, fully configured on Repl.it. For more information about working on Repl.it, see the [Repl.it Quickstart Guide](https://docs.repl.it/misc/quick-start#the-repl-environment). For group assignments, students can use Repl.it Multiplayer to work collaboratively. For more information, see the [Repl.it Multiplayer](https://repl.it/site/multiplayer) website. ### About submission of assignments with Repl.it By default, Repl.it is configured to push to the assignment repository on {% data variables.product.product_location %}. After making progress on an assignment with Repl.it, students should push changes to {% data variables.product.product_location %} using the version control functionality in the left sidebar.  For more information about using Git on Repl.it, see the [Repl.it + Git Tutorial](https://repl.it/talk/learn/Replit-Git-Tutorial/23331) on the Repl.it website. ### Further reading - "[About READMEs](/github/creating-cloning-and-archiving-repositories/about-readmes)" 33 ...anage-coursework-with-github-classroom/basics-of-setting-up-github-classroom.md @@ -0,0 +1,33 @@ --- title: Basics of setting up GitHub Classroom shortTitle: '{% data variables.product.prodname_classroom %} basics' intro: Learn how to set up your classroom, manage assignments, and configure time-saving automation. versions: free-pro-team: '*' --- ### Videos about {% data variables.product.prodname_classroom %} You can watch a series of short video tutorials about the configuration and use of {% data variables.product.prodname_classroom %}. To watch all videos as part of a continuous playlist, see the [{% data variables.product.prodname_classroom %} Getting Started Guide](https://www.youtube.com/playlist?list=PLIRjfNq867bewk3ZGV6Z7a16YDNRCpK3u) on YouTube. For more information about terminology for {% data variables.product.prodname_classroom %}, see "[Glossary](/education/manage-coursework-with-github-classroom/glossary)". 1. <a href="https://youtu.be/xVVeqIDgCvM" target="_blank">Getting started</a> {% octicon "link-external" aria-label="The external link icon" %} 2. <a href="https://youtu.be/DTzrKduaHj8" target="_blank">Adding your student roster</a> {% octicon "link-external" aria-label="The external link icon" %} 3. Creating assignments - <a href="https://youtu.be/6QzKZ63KLss" target="_blank">Creating an assignment using a {% data variables.product.prodname_dotcom %} repository</a> {% octicon "link-external" aria-label="The external link icon" %} - <a href="https://youtu.be/Qmwh6ijsQJU" target="_blank">Creating an assignment using Microsoft MakeCode as your online IDE</a> {% octicon "link-external" aria-label="The external link icon" %} - <a href="https://youtu.be/p_g5sQ7hUis" target="_blank">Creating an assignment using Repl.it as your online IDE</a> {% octicon "link-external" aria-label="The external link icon" %} 4. <a href="https://youtu.be/ObaFRGp_Eko" target="_blank">How students complete assignments</a> {% octicon "link-external" aria-label="The external link icon" %} 5. <a href="https://youtu.be/g45OJn3UyCU" target="_blank">How teachers review assignments</a> {% octicon "link-external" aria-label="The external link icon" %} 6. <a href="https://youtu.be/QxrA3taZdNM" target="_blank">Creating group assignments</a> {% octicon "link-external" aria-label="The external link icon" %} 7. <a href="https://youtu.be/tJK2cmoh1KM" target="_blank">Next steps to get started</a> {% octicon "link-external" aria-label="The external link icon" %} 8. <a href="https://youtu.be/X87v3SFQxLU" target="_blank">{% data variables.product.prodname_dotcom %} Teacher Toolbox</a> {% octicon "link-external" aria-label="The external link icon" %} ### Next steps For more information about teaching with {% data variables.product.prodname_classroom %}, see "[Teach with {% data variables.product.prodname_classroom %}](/education/manage-coursework-with-github-classroom/teach-with-github-classroom)." ### Further reading - "[Teach and learn with {% data variables.product.prodname_education %}](/education/teach-and-learn-with-github-education)" 51 ...with-github-classroom/configure-default-settings-for-assignment-repositories.md @@ -0,0 +1,51 @@ --- title: Configure default settings for assignment repositories shortTitle: Configure defaults for assignment repositories intro: You can use the Probot Settings app to configure the default settings for repositories that {% data variables.product.prodname_classroom %} creates for an assignment. permissions: Organization owners can configure default settings for assignment repositories by installing a {% data variables.product.prodname_github_app %} for the organization. versions: free-pro-team: '*' redirect_from: - /education/manage-coursework-with-github-classroom/probot-settings --- ### About configuration of defaults for assignment repositories {% data variables.product.prodname_classroom %} creates a repository that belongs for each student or team that accepts an assignment. The repository belongs to the organization that you use for {% data variables.product.prodname_classroom %}. Assignment repositories can be empty, or you can use a template repository. For more information, see "[Create an assignment from a template repository](/education/manage-coursework-with-github-classroom/create-an-assignment-from-a-template-repository)." {% data reusables.classroom.you-may-want-to-predefine-repository-settings %} With the Probot Settings app, you can create a file named _.github/settings.yml_ in a repository that contains a list of settings for the repository, and then install a {% data variables.product.prodname_github_app %} for your organization that automatically applies the settings to the repository. You can include _.github/settings.yml_ in a template repository that you use for an assignment in {% data variables.product.prodname_classroom %}. When an individual or team accepts the assignment, {% data variables.product.prodname_classroom %} creates the assignment repository, and the Settings app automatically applies the settings from _.github/settings.yml_. Probot is a a project, framework, and collection of free apps to automate {% data variables.product.product_name %}. A Probot app can listen to repository events, like the creation of new commits, comments, and issues, and automatically respond to the event. For more information, see the [Probot website](https://probot.github.io) and the [Settings app website](https://probot.github.io/apps/settings/). For more information about {% data variables.product.prodname_github_apps %}, see "[About apps](/developers/apps/about-apps)." ### Adding the Settings app to your organization After you install the Probot Settings app for your organization, the app will apply the settings that you define in _.github/settings.yml_ for any repository in your organization, including new assignment repositories that {% data variables.product.prodname_classroom %} creates. 1. Navigate to the [Settings app page](https://github.com/apps/settings). 1. Click **Install**, then click the organization that you use for {% data variables.product.prodname_classroom %}. Provide the app full access to all repositories owned by the organization.  ### Configuring default settings for an assignment repository 1. Create a template repository that contains a _.github/settings.yml_ file. For a complete list of settings, see the [README](https://github.com/probot/settings#github-settings) for the `probot/settings` repository. For more information about using a template repository for starter code in {% data variables.product.prodname_classroom %}, see "[Create an assignment from a template repository](/education/manage-coursework-with-github-classroom/create-an-assignment-from-a-template-repository)." {% warning %} **Warning:** Do not define `collaborators` in the _.github/settings.yml_ file for your template repository. {% data variables.product.prodname_classroom %} automatically grants teachers and teaching assistants access to assignment repositories. {% endwarning %} 1. Create an assignment using the template repository containing _.github/settings.yml_ as the starter code. {% data reusables.classroom.for-more-information-about-assignment-creation %} The Probot Settings app for your organization will now apply the settings you define in _.github/settings.yml_ within the template repository to every assignment repository that {% data reusables.classroom.you-may-want-to-predefine-repository-settings %} creates for a student or team. ### Further reading - [Probot apps](https://probot.github.io/apps/) - [Probot documentation](https://probot.github.io/docs/) 142 ...th-github-classroom/connect-a-learning-management-system-to-github-classroom.md @@ -0,0 +1,142 @@ --- title: Connect a learning management system to GitHub Classroom intro: You can configure an LTI-compliant learning management system (LMS) to connect to {% data variables.product.prodname_classroom %} so that you can import a roster for your classroom. versions: free-pro-team: '*' redirect_from: - /education/manage-coursework-with-github-classroom/configuring-a-learning-management-system-for-github-classroom - /education/manage-coursework-with-github-classroom/connect-to-lms - /education/manage-coursework-with-github-classroom/generate-lms-credentials - /education/manage-coursework-with-github-classroom/setup-canvas - /education/manage-coursework-with-github-classroom/setup-generic-lms - /education/manage-coursework-with-github-classroom/setup-moodle --- ### About configuration of your LMS You can connect a learning management system (LMS) to {% data variables.product.prodname_classroom %}, and {% data variables.product.prodname_classroom %} can import a roster of student identifiers from the LMS. To connect your LMS to {% data variables.product.prodname_classroom %}, you must enter configuration credentials for {% data variables.product.prodname_classroom %} in your LMS. ### Prerequisites To configure an LMS to connect to {% data variables.product.prodname_classroom %}, you must first create a classroom. For more information, see "[Manage classrooms](/education/manage-coursework-with-github-classroom/manage-classrooms#creating-a-classroom)." ### Supported LMSes {% data variables.product.prodname_classroom %} supports import of roster data from LMSes that implement Learning Tools Interoperability (LTI) standards. - LTI version 1.0 and/or 1.1 - LTI Names and Roles Provisioning 1.X Using LTI helps keep your information safe and secure. LTI is an industry-standard protocol and GitHub Classroom's use of LTI is certified by the Instructional Management System (IMS) Global Learning Consortium. For more information, see [Learning Tools Interoperability](https://www.imsglobal.org/activity/learning-tools-interoperability) and [About IMS Global Learning Consortium](http://www.imsglobal.org/aboutims.html) on the IMS Global Learning Consortium website. {% data variables.product.company_short %} has tested import of roster data from the following LMSes into {% data variables.product.prodname_classroom %}. - Canvas - Google Classroom - Moodle - Sakai Currently, {% data variables.product.prodname_classroom %} doesn't support import of roster data from Blackboard or Brightspace ### Generating configuration credentials for your classroom {% data reusables.classroom.sign-into-github-classroom %} {% data reusables.classroom.click-classroom-in-list %} {% data reusables.classroom.click-students %} 1. If your classroom already has a roster, you can either update the roster or delete the roster and create a new roster. - For more information about deleting and creating a roster, see "[Deleting a roster for a classroom](/education/manage-coursework-with-github-classroom/manage-classrooms#deleting-a-roster-for-a-classroom)" and "[Creating a roster for your classroom](/education/manage-coursework-with-github-classroom/manage-classrooms#creating-a-roster-for-your-classroom)." - For more information about updating a roster, see "[Adding students to the roster for your classroom](/education/manage-coursework-with-github-classroom/manage-classrooms#adding-students-to-the-roster-for-your-classroom)." 1. In the list of LMSes, click your LMS. If your LMS is not supported, click **Other LMS**.  1. Read about connecting your LMS, then click **Connect to _LMS_**. 1. Copy the "Consumer Key", "Shared Secret", and "Launch URL" for the connection to the classroom.  ### Configuring a generic LMS You must configure the privacy settings for your LMS to allow external tools to receive roster information. 1. Navigate to your LMS. 1. Configure an external tool. 1. Provide the configuration credentials you generated in {% data variables.product.prodname_classroom %}. - Consumer key - Shared secret - Launch URL (sometimes called "tool URL" or similar) ### Configuring Canvas You can configure {% data variables.product.prodname_classroom %} as an external app for Canvas to import roster data into your classroom. For more information about Canvas, see the [Canvas website](https://www.instructure.com/canvas/). 1. Sign into [Canvas](https://www.instructure.com/canvas/#login). 1. Select the Canvas course to integrate with {% data variables.product.prodname_classroom %}. 1. In the left sidebar, click **Settings**. 1. Click the **Apps** tab. 1. Click **View app configurations**. 1. Click **+App**. 1. Select the **Configuration Type** drop-down menu, and click **By URL**. 1. Paste the configuration credentials from {% data variables.product.prodname_classroom %}. For more information, see "[Generating configuration credentials for your classroom](#generating-configuration-credentials-for-your-classroom)." | Field in Canvas app configuration | Value or setting | | :- | :- | | **Consumer Key** | Consumer key from {% data variables.product.prodname_classroom %} | | **Shared Secret** | Shared secret from {% data variables.product.prodname_classroom %} | | **Allow this tool to access the IMS Names and Role Provisioning Service** | Enabled | | **Configuration URL** | Launch URL from {% data variables.product.prodname_classroom %} | {% note %} **Note**: If you don't see a checkbox in Canvas labeled "Allow this tool to access the IMS Names and Role Provisioning Service", then your Canvas administrator must contact Canvas support to enable membership service configuration for your Canvas account. Without enabling this feature, you won't be able to sync the roster from Canvas. For more information, see [How do I contact Canvas Support?](https://community.canvaslms.com/t5/Canvas-Basics-Guide/How-do-I-contact-Canvas-Support/ta-p/389767) on the Canvas website. {% endnote %} 1. Click **Submit**. 1. In the left sidebar, click **Home**. 1. To prompt Canvas to send a confirmation email, in the left sidebar, click **GitHub Classroom**. Follow the instructions in the email to finish linking {% data variables.product.prodname_classroom %}. ### Configuring Moodle You can configure {% data variables.product.prodname_classroom %} as an activity for Moodle to import roster data into your classroom. For more information about Moodle, see the [Moodle website](https://moodle.org). You must be using Moodle version 3.0 or greater. 1. Sign into [Moodle](https://moodle.org/login/index.php). 1. Select the Moodle course to integrate with {% data variables.product.prodname_classroom %}. 1. Click **Turn editing on**. 1. Wherever you'd like {% data variables.product.prodname_classroom %} to be available in Moodle, click **Add an activity or resource**. 1. Choose **External tool** and click **Add**. 1. In the "Activity name" field, type "GitHub Classroom". 1. In the **Preconfigured tool** field, to the right of the drop-down menu, click **+**. 1. Under "External tool configuration", paste the configuration credentials from {% data variables.product.prodname_classroom %}. For more information, see "[Generating configuration credentials for your classroom](#generating-configuration-credentials-for-your-classroom)." | Field in Moodle app configuration | Value or setting | | :- | :- | | **Tool name** | {% data variables.product.prodname_classroom %} - _YOUR CLASSROOM NAME_<br/><br/>**Note**: You can use any name, but we suggest this value for clarity. | | **Tool URL** | Launch URL from {% data variables.product.prodname_classroom %} | | **LTI version** | LTI 1.0/1.1 | | **Default launch container** | New window | | **Consumer key** | Consumer key from {% data variables.product.prodname_classroom %} | | **Shared secret** | Shared secret from {% data variables.product.prodname_classroom %} | 1. Scroll to and click **Services**. 1. To the right of "IMS LTI Names and Role Provisioning", select the drop-down menu and click **Use this service to retrieve members' information as per privacy settings**. 1. Scroll to and click **Privacy**. 1. To the right of **Share launcher's name with tool** and **Share launcher's email with tool**, select the drop-down menus to click **Always**. 1. At the bottom of the page, click **Save changes**. 1. In the **Preconfigure tool** menu, click **GitHub Classroom - _YOUR CLASSROOM NAME_**. 1. Under "Common module settings", to the right of "Availability", select the drop-down menu and click **Hide from students**. 1. At the bottom of the page, click **Save and return to course**. 1. Navigate to anywhere you chose to display {% data variables.product.prodname_classroom %}, and click the {% data variables.product.prodname_classroom %} activity. ### Importing a roster from your LMS For more information about importing the roster from your LMS into {% data variables.product.prodname_classroom %}, see "[Manage classrooms](/education/manage-coursework-with-github-classroom/manage-classrooms#creating-a-roster-for-your-classroom)." ### Disconnecting your LMS {% data reusables.classroom.sign-into-github-classroom %} {% data reusables.classroom.click-classroom-in-list %} {% data reusables.classroom.click-settings %} 1. Under "Connect to a learning management system (LMS)", click **Connection Settings**.  1. Under "Delete Connection to your learning management system", click **Disconnect from your learning management system**.  145 .../education/manage-coursework-with-github-classroom/create-a-group-assignment.md @@ -0,0 +1,145 @@ --- title: Create a group assignment intro: 'You can create a collaborative assignment for teams of students who participate in your course.' versions: free-pro-team: '*' redirect_from: - /education/manage-coursework-with-github-classroom/create-group-assignments --- ### About group assignments {% data reusables.classroom.assignments-group-definition %} Students can work together on a group assignment in a shared repository, like a team of professional developers. When a student accepts a group assignment, the student can create a new team or join an existing team. {% data variables.product.prodname_classroom %} saves the teams for an assignment as a set. You can name the set of teams for a specific assignment when you create the assignment, and you can reuse that set of teams for a later assignment. {% data reusables.classroom.classroom-creates-group-repositories %} {% data reusables.classroom.about-assignments %} You can decide how many teams one assignment can have, and how many members each team can have. Each team that a student creates for an assignment is a team within your organization on {% data variables.product.product_name %}. The visibility of the team is secret. Teams that you create on {% data variables.product.product_name %} will not appear in {% data variables.product.prodname_classroom %}. For more information, see "[About teams](/github/setting-up-and-managing-organizations-and-teams/about-teams)." For a video demonstration of the creation of a group assignment, see "[Basics of setting up {% data variables.product.prodname_classroom %}](/education/manage-coursework-with-github-classroom/basics-of-setting-up-github-classroom)." ### Prerequisites {% data reusables.classroom.assignments-classroom-prerequisite %} ### Creating an assignment {% data reusables.classroom.assignments-guide-create-the-assignment %} ### Setting up the basics for an assignment Name your assignment, decide whether to assign a deadline, define teams, and choose the visibility of assignment repositories. - [Naming an assignment](#naming-an-assignment) - [Assigning a deadline for an assignment](#assigning-a-deadline-for-an-assignment) - [Choosing an assignment type](#choosing-an-assignment-type) - [Defining teams for an assignment](#defining-teams-for-an-assignment) - [Choosing a visibility for assignment repositories](#choosing-a-visibility-for-assignment-repositories) #### Naming an assignment For a group assignment, {% data variables.product.prodname_classroom %} names repositories by the repository prefix and the name of the team. By default, the repository prefix is the assignment title. For example, if you name an assignment "assignment-1" and the team's name on {% data variables.product.product_name %} is "student-team", the name of the assignment repository for members of the team will be `assignment-1-student-team`. {% data reusables.classroom.assignments-type-a-title %} #### Assigning a deadline for an assignment {% data reusables.classroom.assignments-guide-assign-a-deadline %} #### Choosing an assignment type Under "Individual or group assignment", select the drop-down menu, then click **Group assignment**. You can't change the assignment type after you create the assignment. If you'd rather create a individual assignment, see "[Create an individual assignment](/education/manage-coursework-with-github-classroom/create-an-individual-assignment)." #### Defining teams for an assignment If you've already created a group assignment for the classroom, you can reuse a set of teams for the new assignment. To create a new set with the teams that your students create for the assignment, type the name for the set. Optionally, type the maximum number of team members and total teams. {% tip %} **Tips**: - We recommend including details about the set of teams in the name for the set. For example, if you want to use the set of teams for one assignment, name the set after the assignment. If you want to reuse the set throughout a semester or course, name the set after the semester or course. - If you'd like to assign students to a specific team, give your students a name for the team and provide a list of members. {% endtip %}  #### Choosing a visibility for assignment repositories {% data reusables.classroom.assignments-guide-choose-visibility %} {% data reusables.classroom.assignments-guide-click-continue-after-basics %} ### Adding starter code and configuring a development environment {% data reusables.classroom.assignments-guide-intro-for-environment %} - [Choosing a template repository](#choosing-a-template-repository) - [Choosing an online integrated development environment (IDE)](#choosing-an-online-integrated-development-environment-ide) #### Choosing a template repository By default, a new assignment will create an empty repository for each team that a student creates. {% data reusables.classroom.you-can-choose-a-template-repository %} For more information about template repositories, see "[Creating a template repository](/github/creating-cloning-and-archiving-repositories/creating-a-template-repository)." {% data reusables.classroom.assignments-guide-choose-template-repository %} #### Choosing an online integrated development environment (IDE) {% data reusables.classroom.about-online-ides %} For more information, see "[Integrate {% data variables.product.prodname_classroom %} with an IDE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide)." {% data reusables.classroom.assignments-guide-choose-an-online-ide %} {% data reusables.classroom.assignments-guide-click-continue-after-starter-code-and-feedback %} ### Providing feedback Optionally, you can automatically grade assignments and create a space for discussing each submission with the team. - [Testing assignments automatically](#testing-assignments-automatically) - [Preventing changes to important files](#preventing-changes-to-important-files) - [Creating a pull request for feedback](#creating-a-pull-request-for-feedback) #### Testing assignments automatically {% data reusables.classroom.assignments-guide-using-autograding %} #### Preventing changes to important files {% data reusables.classroom.assignments-guide-prevent-changes %} #### Creating a pull request for feedback {% data reusables.classroom.you-can-create-a-pull-request-for-feedback %} {% data reusables.classroom.assignments-guide-create-review-pull-request %} {% data reusables.classroom.assignments-guide-click-create-assignment-button %} ### Inviting students to an assignment {% data reusables.classroom.assignments-guide-invite-students-to-assignment %} You can see the teams that are working on or have submitted an assignment in the **Teams** tab for the assignment. {% data reusables.classroom.assignments-to-prevent-submission %} <div class="procedural-image-wrapper"> <img alt="Group assignment" class="procedural-image-wrapper" src="/assets/images/help/classroom/assignment-group-hero.png"> </div> ### Next steps - After you create the assignment and your students form teams, team members can start work on the assignment using Git and {% data variables.product.product_name %}'s features. Students can clone the repository, push commits, manage branches, create and review pull requests, address merge conflicts, and discuss changes with issues. Both you and the team can review the commit history for the repository. For more information, see "[Getting started with {% data variables.product.prodname_dotcom %}](/github/getting-started-with-github)," "[Creating, cloning, and archiving repositories](/github/creating-cloning-and-archiving-repositories)," "[Using Git](/github/using-git)," and "[Collaborating with issues and pull requests](/github/collaborating-with-issues-and-pull-requests)," and the free course on [managing merge conflicts](https://lab.github.com/githubtraining/managing-merge-conflicts) from {% data variables.product.prodname_learning %}. - When a team finishes an assignment, you can review the files in the repository, or you can review the history and visualizations for the repository to better understand how the team collaborated. For more information, see "[Visualizing repository data with graphs](/github/visualizing-repository-data-with-graphs)." - You can provide feedback for an assignment by commenting on individual commits or lines in a pull request. For more information, see "[Commenting on a pull request](/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request)" and "[Opening an issue from code](/github/managing-your-work-on-github/opening-an-issue-from-code)." For more information about creating saved replies to provide feedback for common errors, see "[About saved replies](/github/writing-on-github/about-saved-replies)." ### Further reading - "[Use {% data variables.product.prodname_dotcom %} in your classroom and research](/education/teach-and-learn-with-github-education/use-github-in-your-classroom-and-research)" - "[Connect a learning management system to {% data variables.product.prodname_classroom %}](/education/manage-coursework-with-github-classroom/connect-a-learning-management-system-to-github-classroom)" - [Using Existing Teams in Group Assignments?](https://education.github.community/t/using-existing-teams-in-group-assignments/6999) in the {% data variables.product.prodname_education %} Community 19 ...sework-with-github-classroom/create-an-assignment-from-a-template-repository.md @@ -0,0 +1,19 @@ --- title: Create an assignment from a template repository intro: You can create an assignment from a template repository to provide starter code, documentation, and other resources to your students. versions: free-pro-team: '*' redirect_from: - /education/manage-coursework-with-github-classroom/using-template-repos-for-assignments --- You can use a template repository on {% data variables.product.product_name %} as starter code for an assignment on {% data variables.product.prodname_classroom %}. Your template repository can contain boilerplate code, documentation, and other resources for your students. For more information, see "[Creating a template repository](/github/creating-cloning-and-archiving-repositories/creating-a-template-repository)." To use the template repository for your assignment, the template repository must be owned by your organization, or the visibility of the template repository must be public. {% data reusables.classroom.you-may-want-to-predefine-repository-settings %} For more information, see "[Configure default settings for assignment repositories](/education/manage-coursework-with-github-classroom/configure-default-settings-for-assignment-repositories)." ### Further reading - "[Create an individual assignment](/education/manage-coursework-with-github-classroom/create-an-individual-assignment)" - "[Create a group assignment](/education/manage-coursework-with-github-classroom/create-a-group-assignment)" 124 ...tion/manage-coursework-with-github-classroom/create-an-individual-assignment.md @@ -0,0 +1,124 @@ --- title: Create an individual assignment intro: You can create an assignment for students in your course to complete individually. versions: free-pro-team: '*' redirect_from: - /education/manage-coursework-with-github-classroom/creating-an-individual-assignment - /education/manage-coursework-with-github-classroom/create-an-individual-assignment --- ### About individual assignments {% data reusables.classroom.assignments-individual-definition %} {% data reusables.classroom.classroom-creates-individual-repositories %} {% data reusables.classroom.about-assignments %} For a video demonstration of the creation of an individual assignment, see "[Basics of setting up {% data variables.product.prodname_classroom %}](/education/manage-coursework-with-github-classroom/basics-of-setting-up-github-classroom)." ### Prerequisites {% data reusables.classroom.assignments-classroom-prerequisite %} ### Creating an assignment {% data reusables.classroom.assignments-guide-create-the-assignment %} ### Setting up the basics for an assignment Name your assignment, decide whether to assign a deadline, and choose the visibility of assignment repositories. - [Naming an assignment](#naming-an-assignment) - [Assigning a deadline for an assignment](#assigning-a-deadline-for-an-assignment) - [Choosing an assignment type](#choosing-an-assignment-type) - [Choosing a visibility for assignment repositories](#choosing-a-visibility-for-assignment-repositories) #### Naming an assignment For an individual assignment, {% data variables.product.prodname_classroom %} names repositories by the repository prefix and the student's {% data variables.product.product_name %} username. By default, the repository prefix is the assignment title. For example, if you name an assignment "assignment-1" and the student's username on {% data variables.product.product_name %} is @octocat, the name of the assignment repository for @octocat will be `assignment-1-octocat`. {% data reusables.classroom.assignments-type-a-title %} #### Assigning a deadline for an assignment {% data reusables.classroom.assignments-guide-assign-a-deadline %} #### Choosing an assignment type Under "Individual or group assignment", select the drop-down menu, and click **Individual assignment**. You can't change the assignment type after you create the assignment. If you'd rather create a group assignment, see "[Create a group assignment](/education/manage-coursework-with-github-classroom/create-a-group-assignment)." #### Choosing a visibility for assignment repositories {% data reusables.classroom.assignments-guide-choose-visibility %} {% data reusables.classroom.assignments-guide-click-continue-after-basics %} ### Adding starter code and configuring a development environment {% data reusables.classroom.assignments-guide-intro-for-environment %} - [Choosing a template repository](#choosing-a-template-repository) - [Choosing an online integrated development environment (IDE)](#choosing-an-online-integrated-development-environment-ide) #### Choosing a template repository By default, a new assignment will create an empty repository for each student on the roster for the classroom. {% data reusables.classroom.you-can-choose-a-template-repository %} For more information about template repositories, see "[Creating a template repository](/github/creating-cloning-and-archiving-repositories/creating-a-template-repository)." {% data reusables.classroom.assignments-guide-choose-template-repository %} {% data reusables.classroom.assignments-guide-click-continue-after-starter-code-and-feedback %} #### Choosing an online integrated development environment (IDE) {% data reusables.classroom.about-online-ides %} For more information, see "[Integrate {% data variables.product.prodname_classroom %} with an IDE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide)." {% data reusables.classroom.assignments-guide-choose-an-online-ide %} ### Providing feedback for an assignment Optionally, you can automatically grade assignments and create a space for discussing each submission with the student. - [Testing assignments automatically](#testing-assignments-automatically) - [Preventing changes to important files](#preventing-changes-to-important-files) - [Creating a pull request for feedback](#creating-a-pull-request-for-feedback) #### Testing assignments automatically {% data reusables.classroom.assignments-guide-using-autograding %} #### Preventing changes to important files {% data reusables.classroom.assignments-guide-prevent-changes %} #### Creating a pull request for feedback {% data reusables.classroom.you-can-create-a-pull-request-for-feedback %} {% data reusables.classroom.assignments-guide-create-review-pull-request %} {% data reusables.classroom.assignments-guide-click-create-assignment-button %} ### Inviting students to an assignment {% data reusables.classroom.assignments-guide-invite-students-to-assignment %} You can see whether a student has joined the classroom and accepted or submitted an assignment in the **All students** tab for the assignment. {% data reusables.classroom.assignments-to-prevent-submission %} <div class="procedural-image-wrapper"> <img alt="Individual assignment" class="procedural-image-wrapper" src="/assets/images/help/classroom/assignment-individual-hero.png"> </div> ### Next steps - Once you create the assignment, students can start work on the assignment using Git and {% data variables.product.product_name %}'s features. Students can clone the repository, push commits, manage branches, create and review pull requests, address merge conflicts, and discuss changes with issues. Both you and student can review the commit history for the repository. For more information, see "[Getting started with {% data variables.product.prodname_dotcom %}](/github/getting-started-with-github)," "[Creating, cloning, and archiving repositories](/github/creating-cloning-and-archiving-repositories)," "[Using Git](/github/using-git)," and "[Collaborating with issues and pull requests](/github/collaborating-with-issues-and-pull-requests)." - When a student finishes an assignment, you can review the files in the repository, or you can review the history and visualizations for the repository to better understand the student's work. For more information, see "[Visualizing repository data with graphs](/github/visualizing-repository-data-with-graphs)." - You can provide feedback for an assignment by commenting on individual commits or lines in a pull request. For more information, see "[Commenting on a pull request](/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request)" and "[Opening an issue from code](/github/managing-your-work-on-github/opening-an-issue-from-code)." For more information about creating saved replies to provide feedback for common errors, see "[About saved replies](/github/writing-on-github/about-saved-replies)." ### Further reading - "[Use {% data variables.product.prodname_dotcom %} in your classroom and research](/education/teach-and-learn-with-github-education/use-github-in-your-classroom-and-research)" - "[Connect a learning management system to {% data variables.product.prodname_classroom %}](/education/manage-coursework-with-github-classroom/connect-a-learning-management-system-to-github-classroom)" 9 ...on/manage-coursework-with-github-classroom/get-started-with-github-classroom.md @@ -0,0 +1,9 @@ --- title: Get started with GitHub Classroom shortTitle: Get started intro: Learn how to configure and use {% data variables.product.prodname_classroom %} to administer your course. mapTopic: true versions: free-pro-team: '*' --- 52 content/education/manage-coursework-with-github-classroom/glossary.md @@ -0,0 +1,52 @@ --- title: Glossary intro: You can review explanations of terminology for {% data variables.product.prodname_classroom %}. versions: free-pro-team: '*' --- ### assignment An assignment is coursework in {% data variables.product.prodname_classroom %}. A teacher can assign an assignment to an individual student or a group of students. Teachers can import starter code for the assignment, assign students, and create a deadline for each assignment. For more information, see the definitions for "[individual assignment](#individual-assignment)" and "[group assignment](#group-assignment)." --- ### classroom A classroom is the basic unit of {% data variables.product.prodname_classroom %}. Teachers can use a classroom to organize and manage students, teaching assistants, and assignments for a single course. A classroom belongs to an organization on {% data variables.product.prodname_dotcom_the_website %}. To administer a classroom, you must be an organization owner for the organization on {% data variables.product.prodname_dotcom %}. For more information, see "[Manage classrooms](/education/manage-coursework-with-github-classroom/manage-classrooms)." --- ### {% data variables.product.prodname_classroom %} {% data variables.product.prodname_classroom %} is a web application for educators that provides course administration tools integrated with {% data variables.product.prodname_dotcom %}. For more information, see the [{% data variables.product.prodname_classroom %}](https://classroom.github.com/) website. --- ### group assignment {% data reusables.classroom.assignments-group-definition %} For more information, see "[Create a group assignment](/education/manage-coursework-with-github-classroom/create-a-group-assignment)." --- ### identifier An identifier in {% data variables.product.prodname_classroom %} is a unique ID for a student participating in a course. For example, an identifier can be a student name, alphanumeric ID, or email address. --- ### individual assignment {% data reusables.classroom.assignments-individual-definition %} For more information, see "[Create an individual assignment](/education/manage-coursework-with-github-classroom/create-an-individual-assignment)." --- ### roster A roster allows a teacher to manage students and assignment submissions in a classroom on {% data variables.product.prodname_classroom %}. Teachers can create a roster by entering a list of student identifiers, or by connecting {% data variables.product.prodname_classroom %} to a learning management system (LMS). For more information about identifiers, see the definition of "[identifier](#identifier)." For more information about connecting {% data variables.product.prodname_classroom %} to an LMS, see "[Connect a learning management system to {% data variables.product.prodname_classroom %}](/education/manage-coursework-with-github-classroom/connect-a-learning-management-system-to-github-classroom)." --- ### Further reading - "[{% data variables.product.prodname_dotcom %} glossary](/github/getting-started-with-github/github-glossary)" 32 content/education/manage-coursework-with-github-classroom/index.md @@ -0,0 +1,32 @@ --- title: Manage coursework with GitHub Classroom shortTitle: '{% data variables.product.prodname_classroom %}' intro: With {% data variables.product.prodname_classroom %}, you can use {% data variables.product.product_name %} to administer or participate in a course about software development. versions: free-pro-team: '*' --- ### Table of Contents {% topic_link_in_list /get-started-with-github-classroom %} {% link_in_list /basics-of-setting-up-github-classroom %} {% link_in_list /glossary %} {% topic_link_in_list /teach-with-github-classroom %} {% link_in_list /manage-classrooms %} {% link_in_list /create-an-individual-assignment %} {% link_in_list /create-a-group-assignment %} {% link_in_list /create-an-assignment-from-a-template-repository %} {% link_in_list /leave-feedback-with-pull-requests %} {% link_in_list /use-autograding %} {% link_in_list /configure-default-settings-for-assignment-repositories %} {% link_in_list /connect-a-learning-management-system-to-github-classroom %} {% topic_link_in_list /integrate-github-classroom-with-an-ide %} {% link_in_list /integrate-github-classroom-with-an-online-ide %} {% link_in_list /about-using-makecode-arcade-with-github-classroom %} {% link_in_list /about-using-replit-with-github-classroom %} {% link_in_list /run-student-code-in-an-online-ide %} {% topic_link_in_list /learn-with-github-classroom %} {% link_in_list /view-autograding-results %} 8 ...nage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide.md @@ -0,0 +1,8 @@ --- title: Integrate GitHub Classroom with an IDE shortTitle: Integrate with an IDE intro: You can help your students write, test, and debug code by preconfiguring a development environment for assignment repositories on {% data variables.product.prodname_classroom %}. mapTopic: true versions: free-pro-team: '*' --- 42 ...ursework-with-github-classroom/integrate-github-classroom-with-an-online-ide.md @@ -0,0 +1,42 @@ --- title: Integrate GitHub Classroom with an online IDE shortTitle: Integrate with an online IDE intro: You can preconfigure a supported online integrated development environment (IDE) for assignments you create in {% data variables.product.prodname_classroom %}. versions: free-pro-team: '*' redirect_from: - /education/manage-coursework-with-github-classroom/online-ide-integrations --- ### About integration with an online IDE {% data reusables.classroom.about-online-ides %} After a student accepts an assignment with an online IDE, the README file in the student's assignment repository will contain a button to open the assignment in the IDE. The student can begin working immediately, and no additional configuration is necessary.  ### Supported online IDEs {% data variables.product.prodname_classroom %} supports the following online IDEs. You can learn more about the student experience for each IDE. | IDE | More information | | :- | :- | | Microsoft MakeCode Arcade | "[About using MakeCode Arcade with {% data variables.product.prodname_classroom %}](/education/manage-coursework-with-github-classroom/about-using-makecode-arcade-with-github-classroom)" | | Repl.it | "[About using Repl.it with GitHub Classroom](/education/manage-coursework-with-github-classroom/about-using-replit-with-github-classroom)" | ### Configuring an online IDE for an assignment You can choose the online IDE you'd like to use for an assignment when you create an assignment. To learn how to create a new assignment that uses an online IDE, see "[Create an individual assignment](/education/manage-coursework-with-github-classroom/create-an-individual-assignment)" or "[Create a group assignment](/education/manage-coursework-with-github-classroom/create-a-group-assignment)." ### Authorizing the OAuth app for an online IDE The first time you configure an assignment with an online IDE, you must authorize the OAuth app for the online IDE for your organization.  For all repositories, grant the app **read** access to metadata, administration, and code, and **write** access to administration and code. For more information, see "[Authorizing OAuth Apps](/github/authenticating-to-github/authorizing-oauth-apps)." ### Further reading - "[About READMEs](/github/creating-cloning-and-archiving-repositories/about-readmes)" 7 ...ducation/manage-coursework-with-github-classroom/learn-with-github-classroom.md @@ -0,0 +1,7 @@ --- title: Learn with GitHub Classroom intro: You can participate in coursework in {% data variables.product.prodname_classroom %} and see results from your teacher. mapTopic: true versions: free-pro-team: '*' --- 33 ...on/manage-coursework-with-github-classroom/leave-feedback-with-pull-requests.md @@ -0,0 +1,33 @@ --- title: Leave feedback with pull requests intro: You can leave feedback for your students in a special pull request within the repository for each assignment. permissions: People with read permissions to a repository can leave feedback in a pull request for the repository. versions: free-pro-team: '*' redirect_from: - /education/manage-coursework-with-github-classroom/leaving-feedback-in-github --- ### About feedback pull requests for assignments {% data reusables.classroom.you-can-create-a-pull-request-for-feedback %} When you enable the pull request for feedback for an assignment, {% data variables.product.prodname_classroom %} will create a special pull request titled **Feedback** in the assignment repository for each student or team. The pull request automatically shows every commit that a student pushed to the assignment repository's default branch. ### Prerequisites To create and access the feedback pull request, you must enable the feedback pull request when you create the assignment. {% data reusables.classroom.for-more-information-about-assignment-creation %} ### Leaving feedback in a pull request for an assignment {% data reusables.classroom.sign-into-github-classroom %} 1. In the list of classrooms, click the classroom with the assignment you want to review.  {% data reusables.classroom.click-assignment-in-list %} 1. To the right of the submission, click **Review**.  1. Review the pull request. For more information, see "[Commenting on a pull request](/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request)." ### Further reading - "[Integrate {% data variables.product.prodname_classroom %} with an IDE](http://localhost:4000/en/free-pro-team@latest/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide)" 121 content/education/manage-coursework-with-github-classroom/manage-classrooms.md @@ -0,0 +1,121 @@ --- title: Manage classrooms intro: You can create and manage a classroom for each course that you teach using {% data variables.product.prodname_classroom %}. permissions: Organization owners can manage a classroom for an organization. versions: free-pro-team: '*' redirect_from: - /education/manage-coursework-with-github-classroom/archive-a-classroom --- ### About classrooms {% data reusables.classroom.about-classrooms %}  ### About management of classrooms {% data variables.product.prodname_classroom %} uses organization accounts on {% data variables.product.product_name %} to manage permissions, administration, and security for each classroom that you create. Each organization can have multiple classrooms. After you create a classroom, {% data variables.product.prodname_classroom %} will prompt you to invite teaching assistants (TAs) and admins to the classroom. Each classroom can have one or more admins. Admins can be teachers, TAs, or any other course administrator who you'd like to have control over your classrooms on {% data variables.product.prodname_classroom %}. Invite TAs and admins to your classroom by inviting the user accounts on {% data variables.product.product_name %} to your organization as organization owners and sharing the URL for your classrom. Organization owners can administer any classroom for the organization. For more information, see "[Permission levels for an organization](/github/setting-up-and-managing-organizations-and-teams/permission-levels-for-an-organization)" and "[Inviting users to join your organization](/github/setting-up-and-managing-organizations-and-teams/inviting-users-to-join-your-organization)." When you're done using a classroom, you can archive the classroom and refer to the classroom, roster, and assignments later, or you can delete the classroom if you no longer need the classroom. ### About classroom rosters Each classroom has a roster. A roster is a list of identifiers for the students who participate in your course. When you first share the URL for an assignment with a student, the student must sign into {% data variables.product.product_name %} with a user account to link the user account to an identifier for the classroom. After the student links a user account, you can see the associated user account in the roster. You can also see when the student accepts or submits an assignment.  ### Prerequisites You must have an organization account on {% data variables.product.product_name %} to manage classrooms on {% data variables.product.prodname_classroom %}. For more information, see "[Types of {% data variables.product.company_short %} accounts](/github/getting-started-with-github/types-of-github-accounts#organization-accounts)" and "[Creating a new organization from scratch](/github/setting-up-and-managing-organizations-and-teams/creating-a-new-organization-from-scratch)." You must authorize the OAuth app for {% data variables.product.prodname_classroom %} for your organization to manage classrooms for your organization account. For more information, see "[Authorizing OAuth Apps](/github/authenticating-to-github/authorizing-oauth-apps)." ### Creating a classroom {% data reusables.classroom.sign-into-github-classroom %} 1. Click **New classroom**.  {% data reusables.classroom.guide-create-new-classroom %} After you create a classroom, you can begin creating assignments for students. For more information, see "[Create an individual assignment](/education/manage-coursework-with-github-classroom/create-an-individual-assignment)" or "[Create a group assignment](/education/manage-coursework-with-github-classroom/create-a-group-assignment)." ### Creating a roster for your classroom You can create a roster of the students who participate in your course. If your course already has a roster, you can update the students on the roster or delete the roster. For more information, see "[Adding a student to the roster for your classroom](#adding-students-to-the-roster-for-your-classroom)" or "[Deleting a roster for a classroom](#deleting-a-roster-for-a-classroom)." {% data reusables.classroom.sign-into-github-classroom %} {% data reusables.classroom.click-classroom-in-list %} {% data reusables.classroom.click-students %} 1. To connect {% data variables.product.prodname_classroom %} to your LMS and import a roster, click {% octicon "mortar-board" aria-label="The mortar board icon" %} **Import from a learning management system** and follow the instructions. For more information, see "[Connect a learning management system to {% data variables.product.prodname_classroom %}](/education/manage-coursework-with-github-classroom/connect-a-learning-management-system-to-github-classroom)."  1. To create a roster manually, type your student identifiers. Optionally, click **Upload a CSV or text file** to upload a file containing the identifiers.  1. Click **Create roster**.  ### Adding students to the roster for your classroom Your classroom must have an existing roster to add students to the roster. For more information about creating a roster, see "[Creating a roster for your classrom](#creating-a-roster-for-your-classroom)." {% data reusables.classroom.sign-into-github-classroom %} {% data reusables.classroom.click-classroom-in-list %} {% data reusables.classroom.click-students %} 1. To the right of "Classroom roster", click **Update students**.  1. Follow the instructions to add students to the roster. - To import students from an LMS, click **Sync from a learning management system**. For more information about importing a roster from an LMS, see "[Connect a learning management system to {% data variables.product.prodname_classroom %}](/education/manage-coursework-with-github-classroom/connect-a-learning-management-system-to-github-classroom)." - To manually add students, under "Manually add students", click **Upload a CSV or text file** or type the identifiers for the students, then click **Add roster entries**.  ### Renaming a classroom {% data reusables.classroom.sign-into-github-classroom %} {% data reusables.classroom.click-classroom-in-list %} {% data reusables.classroom.click-settings %} 1. Under "Classroom name", type a new name for the classroom.  1. Click **Rename classroom**.  ### Archiving or unarchiving a classroom You can archive a classroom that you no longer use on {% data variables.product.prodname_classroom %}. When you archive a classroom, you can't create new assignments or edit existing assignments for the classroom. Students can't accept invitations to assignments in archived classrooms. {% data reusables.classroom.sign-into-github-classroom %} 1. To the right of a classroom's name, select the {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %} drop-down menu, then click **Archive**.  1. To unarchive a classroom, to the right of a classroom's name, select the {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %} drop-down menu, then click **Unarchive**.  ### Deleting a roster for a classroom {% data reusables.classroom.sign-into-github-classroom %} {% data reusables.classroom.click-classroom-in-list %} {% data reusables.classroom.click-students %} 1. Under "Delete this roster", click **Delete roster**.  1. Read the warnings, then click **Delete roster**.  ### Deleting a classroom {% data reusables.classroom.sign-into-github-classroom %} {% data reusables.classroom.click-classroom-in-list %} {% data reusables.classroom.click-settings %} 1. To the right of "Delete this classroom", click **Delete classroom**.  1. **Read the warnings**. 1. To verify that you're deleting the correct classroom, type the name of the classroom you want to delete.  1. Click **Delete classroom**.  22 ...on/manage-coursework-with-github-classroom/run-student-code-in-an-online-ide.md @@ -0,0 +1,22 @@ --- title: Run student code in an online IDE intro: You can run the code from a student assignment within the online integrated development environment (IDE) that you configured for the assignment. versions: free-pro-team: '*' redirect_from: - /education/manage-coursework-with-github-classroom/running-student-code --- ### About student code and online IDEs If you configure an online integrated development environment (IDE) for an assignment, you can run the code within the online IDE. You don't need to clone the assignment repository to your computer. For more information about online IDEs, see "[Integrate {% data variables.product.prodname_classroom %} with an online IDE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-online-ide)." ### Running student code in the online IDE {% data reusables.classroom.sign-into-github-classroom %} {% data reusables.classroom.click-classroom-in-list %} {% data reusables.classroom.click-assignment-in-list %} 1. To the right of the submission, click **View IDE**.  8 ...ducation/manage-coursework-with-github-classroom/teach-with-github-classroom.md @@ -0,0 +1,8 @@ --- title: Teach with GitHub Classroom intro: Learn how to set up your classroom and assignments. mapTopic: true versions: free-pro-team: '*' --- 93 content/education/manage-coursework-with-github-classroom/use-autograding.md 30 ...t/education/manage-coursework-with-github-classroom/view-autograding-results.md 90 content/education/quickstart.md 1 ...github-education/about-campus-advisors.md → ...github-education/about-campus-advisors.md 1 ...-github-education/about-campus-experts.md → ...-github-education/about-campus-experts.md 1 ...ducation-for-educators-and-researchers.md → ...ducation-for-educators-and-researchers.md 5 ...on/about-github-education-for-students.md → ...on/about-github-education-for-students.md 9 ...ithub-education/about-github-education.md → ...ithub-education/about-github-education.md 5 .../applying-for-a-student-developer-pack.md → ...ion/apply-for-a-student-developer-pack.md 14 ...for-an-educator-or-researcher-discount.md → ...for-an-educator-or-researcher-discount.md 26 content/education/teach-and-learn-with-github-education/index.md 3 ...github-at-your-educational-institution.md → ...github-at-your-educational-institution.md 3 ...ation/using-github-for-your-schoolwork.md → ...ucation/use-github-for-your-schoolwork.md 3 ...-github-in-your-classroom-and-research.md → ...-github-in-your-classroom-and-research.md 5 ...-for-a-student-developer-pack-approved.md → ...-for-a-student-developer-pack-approved.md 3 ...ucator-or-researcher-discount-approved.md → ...ucator-or-researcher-discount-approved.md 20 ...ering-a-repository/enabling-or-disabling-github-discussions-for-a-repository.md 5 content/github/administering-a-repository/index.md 2 content/github/authenticating-to-github/reviewing-your-security-log.md 1 content/github/collaborating-with-issues-and-pull-requests/index.md 74 ...with-issues-and-pull-requests/reviewing-dependency-changes-in-a-pull-request.md 19 ...g-with-issues-and-pull-requests/reviewing-proposed-changes-in-a-pull-request.md 10 content/github/creating-cloning-and-archiving-repositories/about-repositories.md 15 content/github/customizing-your-github-workflow/about-github-marketplace.md 2 content/github/getting-started-with-github/git-and-github-learning-resources.md 4 content/github/getting-started-with-github/github-glossary.md 6 content/github/getting-started-with-github/signing-up-for-a-new-github-account.md 1 content/github/index.md 2 ...b/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies.md 25 ...hub/managing-security-vulnerabilities/about-managing-vulnerable-dependencies.md 1 content/github/managing-security-vulnerabilities/index.md 4 ...nerabilities/viewing-and-updating-vulnerable-dependencies-in-your-repository.md 3 ...criptions-and-notifications-on-github/managing-notifications-from-your-inbox.md 6 content/github/managing-your-work-on-github/about-issues.md 3 content/github/searching-for-information-on-github/about-searching-on-github.md 5 content/github/searching-for-information-on-github/index.md 114 content/github/searching-for-information-on-github/searching-discussions.md 2 ...ithub/searching-for-information-on-github/searching-issues-and-pull-requests.md 2 ...nd-managing-billing-and-payments-on-github/about-billing-for-github-sponsors.md 4 ...-billing-and-payments-on-github/discounted-subscriptions-for-github-accounts.md 19 ...ing-up-and-managing-billing-and-payments-on-github/downgrading-a-sponsorship.md 16 ...tting-up-and-managing-billing-and-payments-on-github/upgrading-a-sponsorship.md 4 content/github/setting-up-and-managing-organizations-and-teams/index.md 27 ...and-teams/managing-discussion-creation-for-repositories-in-your-organization.md 25 ...izations-and-teams/managing-updates-from-accounts-your-organization-sponsors.md 3 ...p-and-managing-organizations-and-teams/permission-levels-for-an-organization.md 14 ...ing-organizations-and-teams/repository-permission-levels-for-an-organization.md 86 ...naging-organizations-and-teams/reviewing-the-audit-log-for-your-organization.md 1 content/github/setting-up-and-managing-your-github-user-account/index.md 24 ...etting-up-and-managing-your-github-user-account/managing-your-theme-settings.md 12 content/github/site-policy/github-additional-product-terms.md 8 ...porting-the-open-source-community-with-github-sponsors/about-github-sponsors.md 17 ...community-with-github-sponsors/attributing-sponsorships-to-your-organization.md 28 ...e-open-source-community-with-github-sponsors/changing-your-sponsorship-tiers.md 22 ...th-github-sponsors/configuring-webhooks-for-events-in-your-sponsored-account.md 17 ...ting-the-open-source-community-with-github-sponsors/contacting-your-sponsors.md 25 ...munity-with-github-sponsors/editing-your-profile-details-for-github-sponsors.md 1 content/github/supporting-the-open-source-community-with-github-sponsors/index.md 12 ...ce-community-with-github-sponsors/managing-your-payouts-from-github-sponsors.md 18 ...he-open-source-community-with-github-sponsors/managing-your-sponsorship-goal.md 39 ...ing-the-open-source-community-with-github-sponsors/managing-your-sponsorship.md 10 ...munity-with-github-sponsors/setting-up-github-sponsors-for-your-organization.md 10 ...munity-with-github-sponsors/setting-up-github-sponsors-for-your-user-account.md 62 ...-source-community-with-github-sponsors/sponsoring-an-open-source-contributor.md 27 ...source-community-with-github-sponsors/viewing-your-sponsors-and-sponsorships.md 23 content/github/teaching-and-learning-with-github-education/index.md This file was deleted. 7 ...nt/github/visualizing-repository-data-with-graphs/about-the-dependency-graph.md 1 content/github/working-with-github-support/index.md 10 content/graphql/README.md 58 ...tting-started-with-github-container-registry/about-github-container-registry.md This file was deleted. 15 content/packages/getting-started-with-github-container-registry/index.md This file was deleted. 95 content/packages/guides/about-github-container-registry.md 2 ...ol-and-visibility-for-container-images.md → ...ol-and-visibility-for-container-images.md 5 ...che-maven-for-use-with-github-packages.md → ...che-maven-for-use-with-github-packages.md 1 ...ng-docker-for-use-with-github-packages.md → ...ng-docker-for-use-with-github-packages.md 1 ...otnet-cli-for-use-with-github-packages.md → ...otnet-cli-for-use-with-github-packages.md 1 ...ng-gradle-for-use-with-github-packages.md → ...ng-gradle-for-use-with-github-packages.md 1 ...uring-npm-for-use-with-github-packages.md → ...uring-npm-for-use-with-github-packages.md 1 ...-rubygems-for-use-with-github-packages.md → ...-rubygems-for-use-with-github-packages.md 2 ...ting-a-repository-to-a-container-image.md → ...ting-a-repository-to-a-container-image.md 10 content/packages/guides/container-guides-for-github-packages.md 2 ...er-registry/deleting-a-container-image.md → ...ages/guides/deleting-a-container-image.md 2 ...ry/enabling-improved-container-support.md → ...es/enabling-improved-container-support.md 33 content/packages/guides/index.md 2 ...b-container-registry-for-docker-images.md → ...b-container-registry-for-docker-images.md 10 content/packages/guides/package-client-guides-for-github-packages.md 2 ...stry/pushing-and-pulling-docker-images.md → ...ides/pushing-and-pulling-docker-images.md 1 ...ng-github-packages-with-github-actions.md → ...ng-github-packages-with-github-actions.md 46 content/packages/index.md 60 ...anaging-packages/about-github-packages.md → ...-github-packages/about-github-packages.md 13 ...concepts-for-github-container-registry.md → ...ages/core-concepts-for-github-packages.md 16 content/packages/learn-github-packages/index.md 1 ...managing-packages/publishing-a-package.md → ...n-github-packages/publishing-a-package.md 3 ...d-managing-packages/deleting-a-package.md → ...ges/manage-packages/deleting-a-package.md 8 ...publishing-and-managing-packages/index.md → content/packages/manage-packages/index.md 1 ...managing-packages/installing-a-package.md → ...s/manage-packages/installing-a-package.md 1 ...and-managing-packages/viewing-packages.md → ...kages/manage-packages/viewing-packages.md 11 content/packages/managing-container-images-with-github-container-registry/index.md This file was deleted. 109 content/packages/quickstart.md 20 content/packages/using-github-packages-with-your-projects-ecosystem/index.md This file was deleted. 10 content/rest/README.md 18 content/rest/overview/resources-in-the-rest-api.md 2 content/rest/overview/troubleshooting.md 10 content/rest/reference/enterprise-admin.md 2 data/products.yml 2 data/reusables/accounts/create-account.md 2 data/reusables/actions/actions-not-verified.md 7 data/reusables/actions/visualization-beta.md 5 data/reusables/audit_log/audit-log-api-info.md 1 data/reusables/audit_log/audit-log-git-events-retention.md 1 data/reusables/classroom/about-assignments.md 1 data/reusables/classroom/about-autograding.md 1 data/reusables/classroom/about-classrooms.md 1 data/reusables/classroom/about-online-ides.md 1 data/reusables/classroom/assignments-classroom-prerequisite.md 2 data/reusables/classroom/assignments-click-pencil.md 1 data/reusables/classroom/assignments-group-definition.md 5 data/reusables/classroom/assignments-guide-assign-a-deadline.md 5 data/reusables/classroom/assignments-guide-choose-an-online-ide.md 5 data/reusables/classroom/assignments-guide-choose-template-repository.md 9 data/reusables/classroom/assignments-guide-choose-visibility.md 7 data/reusables/classroom/assignments-guide-click-continue-after-basics.md 7 ...s/classroom/assignments-guide-click-continue-after-starter-code-and-feedback.md 5 data/reusables/classroom/assignments-guide-click-create-assignment-button.md 5 data/reusables/classroom/assignments-guide-create-review-pull-request.md 5 data/reusables/classroom/assignments-guide-create-the-assignment.md 1 data/reusables/classroom/assignments-guide-intro-for-environment.md 3 data/reusables/classroom/assignments-guide-invite-students-to-assignment.md 7 data/reusables/classroom/assignments-guide-prevent-changes.md 23 data/reusables/classroom/assignments-guide-using-autograding.md 1 data/reusables/classroom/assignments-individual-definition.md 1 data/reusables/classroom/assignments-to-prevent-submission.md 5 data/reusables/classroom/assignments-type-a-title.md 1 data/reusables/classroom/classroom-creates-group-repositories.md 1 data/reusables/classroom/classroom-creates-individual-repositories.md 1 data/reusables/classroom/classroom-enables-invitation-urls.md 2 data/reusables/classroom/click-assignment-in-list.md 2 data/reusables/classroom/click-classroom-in-list.md 2 data/reusables/classroom/click-settings.md 2 data/reusables/classroom/click-students.md 1 data/reusables/classroom/for-more-information-about-assignment-creation.md 6 data/reusables/classroom/guide-create-new-classroom.md 5 data/reusables/classroom/invitation-url-warning.md 1 data/reusables/classroom/readme-contains-button-for-online-ide.md 1 data/reusables/classroom/sign-into-github-classroom.md 1 data/reusables/classroom/use-add-test-drop-down-to-click-grading-method.md 1 data/reusables/classroom/you-can-choose-a-template-repository.md 1 data/reusables/classroom/you-can-create-a-pull-request-for-feedback.md 1 data/reusables/classroom/you-may-want-to-predefine-repository-settings.md 1 data/reusables/discussions/about-categories-and-formats.md 1 data/reusables/discussions/about-discussions.md 5 data/reusables/discussions/beta.md 2 data/reusables/discussions/click-discussion-in-list.md 2 data/reusables/discussions/discussions-tab.md 2 data/reusables/discussions/edit-categories.md 1 data/reusables/discussions/edit-category-details.md 8 ...les/discussions/enabling-or-disabling-github-discussions-for-your-repository.md 1 data/reusables/discussions/github-recognizes-members.md 16 data/reusables/discussions/marking-a-comment-as-an-answer.md 1 data/reusables/discussions/repository-category-limit.md 10 data/reusables/discussions/starting-a-discussion.md 1 data/reusables/discussions/you-can-categorize-discussions.md 1 data/reusables/discussions/you-can-convert-an-issue.md 1 data/reusables/discussions/you-can-use-discussions.md 1 data/reusables/discussions/you-cannot-convert-a-discussion.md 2 data/reusables/education/about-github-education-link.md 2 data/reusables/education/apply-for-team.md 2 data/reusables/education/click-get-teacher-benefits.md 6 data/reusables/education/educator-requirements.md 1 data/reusables/gated-features/discussions.md 1 data/reusables/marketplace/app-transfer-to-org-for-verification.md 5 data/reusables/marketplace/free-plan-note.md 2 data/reusables/marketplace/launch-with-free.md 8 data/reusables/marketplace/marketplace-billing-ui-requirements.md 2 data/reusables/package_registry/billing-for-container-registry.md 2 data/reusables/package_registry/container-registry-beta-billing-note.md 2 data/reusables/package_registry/container-registry-beta.md 2 data/reusables/package_registry/docker_registry_deprecation_status.md 2 data/reusables/package_registry/feature-preview-for-container-registry.md 2 data/reusables/package_registry/required-scopes.md 2 data/reusables/package_registry/viewing-packages.md 3 data/reusables/repositories/dependency-review.md 7 data/reusables/repositories/navigate-to-job-superlinter.md 4 data/reusables/repositories/view-failed-job-results-superlinter.md 4 data/reusables/repositories/view-specific-line-superlinter.md 2 data/reusables/search/date_gt_lt.md 2 data/reusables/sponsors/billing-switcher.md 2 data/reusables/sponsors/change-tier.md 2 data/reusables/sponsors/choose-updates.md 2 data/reusables/sponsors/developer-sponsored-choose-updates.md This file was deleted. 4 data/reusables/sponsors/manage-developer-sponsorship.md This file was deleted. 4 data/reusables/sponsors/manage-org-sponsorship.md This file was deleted. 2 data/reusables/sponsors/manage-sponsorship.md 1 data/reusables/sponsors/manage-updates-for-orgs.md 2 data/reusables/sponsors/maximum-tier.md 4 data/reusables/sponsors/navigate-to-org-sponsors-dashboard.md This file was deleted. 2 ...onsors/navigate-to-sponsored-developer.md → ...sponsors/navigate-to-sponsored-account.md 1 data/reusables/sponsors/navigate-to-sponsored-org.md This file was deleted. 2 ...ors/navigate-to-dev-sponsors-dashboard.md → ...ponsors/navigate-to-sponsors-dashboard.md 2 data/reusables/sponsors/no-fees.md 5 data/reusables/sponsors/org-sponsors-release-phase.md 2 data/reusables/sponsors/pay-prorated-amount.md 2 data/reusables/sponsors/prorated-sponsorship.md 2 data/reusables/sponsors/sponsor-account.md 7 data/reusables/sponsors/sponsorship-dashboard.md 2 data/reusables/sponsors/sponsorship-details.md 1 data/reusables/webhooks/app_always_desc.md 3 data/ui.yml 7 data/variables/action_code_examples.yml 37 data/variables/discussions_community_examples.yml 6 data/variables/product.yml 21 includes/all-articles.html 4 includes/breadcrumbs.html 2 includes/code-example-card.html 14 includes/discussions-community-card.html 2 includes/header-notification.html 90 javascripts/filter-cards.js 92 javascripts/filter-code-examples.js This file was deleted. 4 javascripts/index.js 64 layouts/product-landing.html 68 lib/data-directory.js 28 lib/filename-to-key.js 7 lib/frontmatter.js 2 lib/liquid-tags/data.js 25 lib/page.js 54 lib/pages.js 21 lib/redirects/get-docs-path-from-developer-path.js 41 lib/redirects/precompile.js 231 lib/rest/static/decorated/api.github.com.json 495 lib/rest/static/dereferenced/api.github.com.deref.json 17 lib/rewrite-local-links.js 10 lib/site-data.js 24 lib/warm-server.js 5 middleware/breadcrumbs.js 38 middleware/categories-for-support-team.js 6 middleware/contextualizers/early-access-links.js 103 middleware/csp.js 69 middleware/early-access-breadcrumbs.js 1 middleware/index.js 45 package-lock.json 3 package.json 4 script/check-s3-images.js 4 script/early-access/clone-locally 41 script/early-access/create-branch 7 server.js 2 stylesheets/article.scss 4 tests/browser/browser.js 10 tests/content/category-pages.js 2 tests/content/crowdin-config.js 3 tests/content/featured-links.js 5 tests/content/glossary.js 42 tests/content/remove-liquid-statements.js 39 tests/content/site-data-references.js 4 tests/content/site-data.js 22 tests/fixtures/rest-redirects.json 10 tests/graphql/build-changelog-test.js 9 tests/helpers/conditional-runs.js 20 tests/meta/orphan-tests.js 23 tests/rendering/breadcrumbs.js 4 tests/rendering/rest.js 3 tests/rendering/server.js 47 tests/routing/developer-site-redirects.js 10 tests/routing/redirects.js 15 tests/unit/data-directory/filename-to-key.js 1 tests/unit/data-directory/fixtures/README.md 1 tests/unit/data-directory/fixtures/bar.yaml 1 tests/unit/data-directory/fixtures/foo.json 1 tests/unit/data-directory/fixtures/nested/baz.md 40 tests/unit/data-directory/index.js 19 tests/unit/early-access.js 4 tests/unit/find-page.js 57 tests/unit/liquid-helpers.js 140 tests/unit/page.js 2 tests/unit/pages.js 0 comments on commit 1a56ed1 Leave a comment You’re not receiving notifications from this thread. © 2021 GitHub, Inc. Terms Privacy Security Status Docs Contact GitHub Pricing API Training Blog About
rramatchandran / Big O Performance Java# big-o-performance A simple html app to demonstrate performance costs of data structures. - Clone the project - Navigate to the root of the project in a termina or command prompt - Run 'npm install' - Run 'npm start' - Go to the URL specified in the terminal or command prompt to try out the app. # This app was created from the Create React App NPM. Below are instructions from that project. Below you will find some information on how to perform common tasks. You can find the most recent version of this guide [here](https://github.com/facebookincubator/create-react-app/blob/master/template/README.md). ## Table of Contents - [Updating to New Releases](#updating-to-new-releases) - [Sending Feedback](#sending-feedback) - [Folder Structure](#folder-structure) - [Available Scripts](#available-scripts) - [npm start](#npm-start) - [npm run build](#npm-run-build) - [npm run eject](#npm-run-eject) - [Displaying Lint Output in the Editor](#displaying-lint-output-in-the-editor) - [Installing a Dependency](#installing-a-dependency) - [Importing a Component](#importing-a-component) - [Adding a Stylesheet](#adding-a-stylesheet) - [Post-Processing CSS](#post-processing-css) - [Adding Images and Fonts](#adding-images-and-fonts) - [Adding Bootstrap](#adding-bootstrap) - [Adding Flow](#adding-flow) - [Adding Custom Environment Variables](#adding-custom-environment-variables) - [Integrating with a Node Backend](#integrating-with-a-node-backend) - [Proxying API Requests in Development](#proxying-api-requests-in-development) - [Deployment](#deployment) - [Now](#now) - [Heroku](#heroku) - [Surge](#surge) - [GitHub Pages](#github-pages) - [Something Missing?](#something-missing) ## Updating to New Releases Create React App is divided into two packages: * `create-react-app` is a global command-line utility that you use to create new projects. * `react-scripts` is a development dependency in the generated projects (including this one). You almost never need to update `create-react-app` itself: it’s delegates all the setup to `react-scripts`. When you run `create-react-app`, it always creates the project with the latest version of `react-scripts` so you’ll get all the new features and improvements in newly created apps automatically. To update an existing project to a new version of `react-scripts`, [open the changelog](https://github.com/facebookincubator/create-react-app/blob/master/CHANGELOG.md), find the version you’re currently on (check `package.json` in this folder if you’re not sure), and apply the migration instructions for the newer versions. In most cases bumping the `react-scripts` version in `package.json` and running `npm install` in this folder should be enough, but it’s good to consult the [changelog](https://github.com/facebookincubator/create-react-app/blob/master/CHANGELOG.md) for potential breaking changes. We commit to keeping the breaking changes minimal so you can upgrade `react-scripts` painlessly. ## Sending Feedback We are always open to [your feedback](https://github.com/facebookincubator/create-react-app/issues). ## Folder Structure After creation, your project should look like this: ``` my-app/ README.md index.html favicon.ico node_modules/ package.json src/ App.css App.js index.css index.js logo.svg ``` For the project to build, **these files must exist with exact filenames**: * `index.html` is the page template; * `favicon.ico` is the icon you see in the browser tab; * `src/index.js` is the JavaScript entry point. You can delete or rename the other files. You may create subdirectories inside `src`. For faster rebuilds, only files inside `src` are processed by Webpack. You need to **put any JS and CSS files inside `src`**, or Webpack won’t see them. You can, however, create more top-level directories. They will not be included in the production build so you can use them for things like documentation. ## Available Scripts In the project directory, you can run: ### `npm start` Runs the app in the development mode.<br> Open [http://localhost:3000](http://localhost:3000) to view it in the browser. The page will reload if you make edits.<br> You will also see any lint errors in the console. ### `npm run build` Builds the app for production to the `build` folder.<br> It correctly bundles React in production mode and optimizes the build for the best performance. The build is minified and the filenames include the hashes.<br> Your app is ready to be deployed! ### `npm run eject` **Note: this is a one-way operation. Once you `eject`, you can’t go back!** If you aren’t satisfied with the build tool and configuration choices, you can `eject` at any time. This command will remove the single build dependency from your project. Instead, it will copy all the configuration files and the transitive dependencies (Webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own. You don’t have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it. ## Displaying Lint Output in the Editor >Note: this feature is available with `react-scripts@0.2.0` and higher. Some editors, including Sublime Text, Atom, and Visual Studio Code, provide plugins for ESLint. They are not required for linting. You should see the linter output right in your terminal as well as the browser console. However, if you prefer the lint results to appear right in your editor, there are some extra steps you can do. You would need to install an ESLint plugin for your editor first. >**A note for Atom `linter-eslint` users** >If you are using the Atom `linter-eslint` plugin, make sure that **Use global ESLint installation** option is checked: ><img src="http://i.imgur.com/yVNNHJM.png" width="300"> Then make sure `package.json` of your project ends with this block: ```js { // ... "eslintConfig": { "extends": "./node_modules/react-scripts/config/eslint.js" } } ``` Projects generated with `react-scripts@0.2.0` and higher should already have it. If you don’t need ESLint integration with your editor, you can safely delete those three lines from your `package.json`. Finally, you will need to install some packages *globally*: ```sh npm install -g eslint babel-eslint eslint-plugin-react eslint-plugin-import eslint-plugin-jsx-a11y eslint-plugin-flowtype ``` We recognize that this is suboptimal, but it is currently required due to the way we hide the ESLint dependency. The ESLint team is already [working on a solution to this](https://github.com/eslint/eslint/issues/3458) so this may become unnecessary in a couple of months. ## Installing a Dependency The generated project includes React and ReactDOM as dependencies. It also includes a set of scripts used by Create React App as a development dependency. You may install other dependencies (for example, React Router) with `npm`: ``` npm install --save <library-name> ``` ## Importing a Component This project setup supports ES6 modules thanks to Babel. While you can still use `require()` and `module.exports`, we encourage you to use [`import` and `export`](http://exploringjs.com/es6/ch_modules.html) instead. For example: ### `Button.js` ```js import React, { Component } from 'react'; class Button extends Component { render() { // ... } } export default Button; // Don’t forget to use export default! ``` ### `DangerButton.js` ```js import React, { Component } from 'react'; import Button from './Button'; // Import a component from another file class DangerButton extends Component { render() { return <Button color="red" />; } } export default DangerButton; ``` Be aware of the [difference between default and named exports](http://stackoverflow.com/questions/36795819/react-native-es-6-when-should-i-use-curly-braces-for-import/36796281#36796281). It is a common source of mistakes. We suggest that you stick to using default imports and exports when a module only exports a single thing (for example, a component). That’s what you get when you use `export default Button` and `import Button from './Button'`. Named exports are useful for utility modules that export several functions. A module may have at most one default export and as many named exports as you like. Learn more about ES6 modules: * [When to use the curly braces?](http://stackoverflow.com/questions/36795819/react-native-es-6-when-should-i-use-curly-braces-for-import/36796281#36796281) * [Exploring ES6: Modules](http://exploringjs.com/es6/ch_modules.html) * [Understanding ES6: Modules](https://leanpub.com/understandinges6/read#leanpub-auto-encapsulating-code-with-modules) ## Adding a Stylesheet This project setup uses [Webpack](https://webpack.github.io/) for handling all assets. Webpack offers a custom way of “extending” the concept of `import` beyond JavaScript. To express that a JavaScript file depends on a CSS file, you need to **import the CSS from the JavaScript file**: ### `Button.css` ```css .Button { padding: 20px; } ``` ### `Button.js` ```js import React, { Component } from 'react'; import './Button.css'; // Tell Webpack that Button.js uses these styles class Button extends Component { render() { // You can use them as regular CSS styles return <div className="Button" />; } } ``` **This is not required for React** but many people find this feature convenient. You can read about the benefits of this approach [here](https://medium.com/seek-ui-engineering/block-element-modifying-your-javascript-components-d7f99fcab52b). However you should be aware that this makes your code less portable to other build tools and environments than Webpack. In development, expressing dependencies this way allows your styles to be reloaded on the fly as you edit them. In production, all CSS files will be concatenated into a single minified `.css` file in the build output. If you are concerned about using Webpack-specific semantics, you can put all your CSS right into `src/index.css`. It would still be imported from `src/index.js`, but you could always remove that import if you later migrate to a different build tool. ## Post-Processing CSS This project setup minifies your CSS and adds vendor prefixes to it automatically through [Autoprefixer](https://github.com/postcss/autoprefixer) so you don’t need to worry about it. For example, this: ```css .App { display: flex; flex-direction: row; align-items: center; } ``` becomes this: ```css .App { display: -webkit-box; display: -ms-flexbox; display: flex; -webkit-box-orient: horizontal; -webkit-box-direction: normal; -ms-flex-direction: row; flex-direction: row; -webkit-box-align: center; -ms-flex-align: center; align-items: center; } ``` There is currently no support for preprocessors such as Less, or for sharing variables across CSS files. ## Adding Images and Fonts With Webpack, using static assets like images and fonts works similarly to CSS. You can **`import` an image right in a JavaScript module**. This tells Webpack to include that image in the bundle. Unlike CSS imports, importing an image or a font gives you a string value. This value is the final image path you can reference in your code. Here is an example: ```js import React from 'react'; import logo from './logo.png'; // Tell Webpack this JS file uses this image console.log(logo); // /logo.84287d09.png function Header() { // Import result is the URL of your image return <img src={logo} alt="Logo" />; } export default function Header; ``` This works in CSS too: ```css .Logo { background-image: url(./logo.png); } ``` Webpack finds all relative module references in CSS (they start with `./`) and replaces them with the final paths from the compiled bundle. If you make a typo or accidentally delete an important file, you will see a compilation error, just like when you import a non-existent JavaScript module. The final filenames in the compiled bundle are generated by Webpack from content hashes. If the file content changes in the future, Webpack will give it a different name in production so you don’t need to worry about long-term caching of assets. Please be advised that this is also a custom feature of Webpack. **It is not required for React** but many people enjoy it (and React Native uses a similar mechanism for images). However it may not be portable to some other environments, such as Node.js and Browserify. If you prefer to reference static assets in a more traditional way outside the module system, please let us know [in this issue](https://github.com/facebookincubator/create-react-app/issues/28), and we will consider support for this. ## Adding Bootstrap You don’t have to use [React Bootstrap](https://react-bootstrap.github.io) together with React but it is a popular library for integrating Bootstrap with React apps. If you need it, you can integrate it with Create React App by following these steps: Install React Bootstrap and Bootstrap from NPM. React Bootstrap does not include Bootstrap CSS so this needs to be installed as well: ``` npm install react-bootstrap --save npm install bootstrap@3 --save ``` Import Bootstrap CSS and optionally Bootstrap theme CSS in the ```src/index.js``` file: ```js import 'bootstrap/dist/css/bootstrap.css'; import 'bootstrap/dist/css/bootstrap-theme.css'; ``` Import required React Bootstrap components within ```src/App.js``` file or your custom component files: ```js import { Navbar, Jumbotron, Button } from 'react-bootstrap'; ``` Now you are ready to use the imported React Bootstrap components within your component hierarchy defined in the render method. Here is an example [`App.js`](https://gist.githubusercontent.com/gaearon/85d8c067f6af1e56277c82d19fd4da7b/raw/6158dd991b67284e9fc8d70b9d973efe87659d72/App.js) redone using React Bootstrap. ## Adding Flow Flow typing is currently [not supported out of the box](https://github.com/facebookincubator/create-react-app/issues/72) with the default `.flowconfig` generated by Flow. If you run it, you might get errors like this: ```js node_modules/fbjs/lib/Deferred.js.flow:60 60: Promise.prototype.done.apply(this._promise, arguments); ^^^^ property `done`. Property not found in 495: declare class Promise<+R> { ^ Promise. See lib: /private/tmp/flow/flowlib_34952d31/core.js:495 node_modules/fbjs/lib/shallowEqual.js.flow:29 29: return x !== 0 || 1 / (x: $FlowIssue) === 1 / (y: $FlowIssue); ^^^^^^^^^^ identifier `$FlowIssue`. Could not resolve name src/App.js:3 3: import logo from './logo.svg'; ^^^^^^^^^^^^ ./logo.svg. Required module not found src/App.js:4 4: import './App.css'; ^^^^^^^^^^^ ./App.css. Required module not found src/index.js:5 5: import './index.css'; ^^^^^^^^^^^^^ ./index.css. Required module not found ``` To fix this, change your `.flowconfig` to look like this: ```ini [libs] ./node_modules/fbjs/flow/lib [options] esproposal.class_static_fields=enable esproposal.class_instance_fields=enable module.name_mapper='^\(.*\)\.css$' -> 'react-scripts/config/flow/css' module.name_mapper='^\(.*\)\.\(jpg\|png\|gif\|eot\|otf\|webp\|svg\|ttf\|woff\|woff2\|mp4\|webm\)$' -> 'react-scripts/config/flow/file' suppress_type=$FlowIssue suppress_type=$FlowFixMe ``` Re-run flow, and you shouldn’t get any extra issues. If you later `eject`, you’ll need to replace `react-scripts` references with the `<PROJECT_ROOT>` placeholder, for example: ```ini module.name_mapper='^\(.*\)\.css$' -> '<PROJECT_ROOT>/config/flow/css' module.name_mapper='^\(.*\)\.\(jpg\|png\|gif\|eot\|otf\|webp\|svg\|ttf\|woff\|woff2\|mp4\|webm\)$' -> '<PROJECT_ROOT>/config/flow/file' ``` We will consider integrating more tightly with Flow in the future so that you don’t have to do this. ## Adding Custom Environment Variables >Note: this feature is available with `react-scripts@0.2.3` and higher. Your project can consume variables declared in your environment as if they were declared locally in your JS files. By default you will have `NODE_ENV` defined for you, and any other environment variables starting with `REACT_APP_`. These environment variables will be defined for you on `process.env`. For example, having an environment variable named `REACT_APP_SECRET_CODE` will be exposed in your JS as `process.env.REACT_APP_SECRET_CODE`, in addition to `process.env.NODE_ENV`. These environment variables can be useful for displaying information conditionally based on where the project is deployed or consuming sensitive data that lives outside of version control. First, you need to have environment variables defined, which can vary between OSes. For example, let's say you wanted to consume a secret defined in the environment inside a `<form>`: ```jsx render() { return ( <div> <small>You are running this application in <b>{process.env.NODE_ENV}</b> mode.</small> <form> <input type="hidden" defaultValue={process.env.REACT_APP_SECRET_CODE} /> </form> </div> ); } ``` The above form is looking for a variable called `REACT_APP_SECRET_CODE` from the environment. In order to consume this value, we need to have it defined in the environment: ### Windows (cmd.exe) ```cmd set REACT_APP_SECRET_CODE=abcdef&&npm start ``` (Note: the lack of whitespace is intentional.) ### Linux, OS X (Bash) ```bash REACT_APP_SECRET_CODE=abcdef npm start ``` > Note: Defining environment variables in this manner is temporary for the life of the shell session. Setting permanent environment variables is outside the scope of these docs. With our environment variable defined, we start the app and consume the values. Remember that the `NODE_ENV` variable will be set for you automatically. When you load the app in the browser and inspect the `<input>`, you will see its value set to `abcdef`, and the bold text will show the environment provided when using `npm start`: ```html <div> <small>You are running this application in <b>development</b> mode.</small> <form> <input type="hidden" value="abcdef" /> </form> </div> ``` Having access to the `NODE_ENV` is also useful for performing actions conditionally: ```js if (process.env.NODE_ENV !== 'production') { analytics.disable(); } ``` ## Integrating with a Node Backend Check out [this tutorial](https://www.fullstackreact.com/articles/using-create-react-app-with-a-server/) for instructions on integrating an app with a Node backend running on another port, and using `fetch()` to access it. You can find the companion GitHub repository [here](https://github.com/fullstackreact/food-lookup-demo). ## Proxying API Requests in Development >Note: this feature is available with `react-scripts@0.2.3` and higher. People often serve the front-end React app from the same host and port as their backend implementation. For example, a production setup might look like this after the app is deployed: ``` / - static server returns index.html with React app /todos - static server returns index.html with React app /api/todos - server handles any /api/* requests using the backend implementation ``` Such setup is **not** required. However, if you **do** have a setup like this, it is convenient to write requests like `fetch('/api/todos')` without worrying about redirecting them to another host or port during development. To tell the development server to proxy any unknown requests to your API server in development, add a `proxy` field to your `package.json`, for example: ```js "proxy": "http://localhost:4000", ``` This way, when you `fetch('/api/todos')` in development, the development server will recognize that it’s not a static asset, and will proxy your request to `http://localhost:4000/api/todos` as a fallback. Conveniently, this avoids [CORS issues](http://stackoverflow.com/questions/21854516/understanding-ajax-cors-and-security-considerations) and error messages like this in development: ``` Fetch API cannot load http://localhost:4000/api/todos. No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://localhost:3000' is therefore not allowed access. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled. ``` Keep in mind that `proxy` only has effect in development (with `npm start`), and it is up to you to ensure that URLs like `/api/todos` point to the right thing in production. You don’t have to use the `/api` prefix. Any unrecognized request will be redirected to the specified `proxy`. Currently the `proxy` option only handles HTTP requests, and it won’t proxy WebSocket connections. If the `proxy` option is **not** flexible enough for you, alternatively you can: * Enable CORS on your server ([here’s how to do it for Express](http://enable-cors.org/server_expressjs.html)). * Use [environment variables](#adding-custom-environment-variables) to inject the right server host and port into your app. ## Deployment By default, Create React App produces a build assuming your app is hosted at the server root. To override this, specify the `homepage` in your `package.json`, for example: ```js "homepage": "http://mywebsite.com/relativepath", ``` This will let Create React App correctly infer the root path to use in the generated HTML file. ### Now See [this example](https://github.com/xkawi/create-react-app-now) for a zero-configuration single-command deployment with [now](https://zeit.co/now). ### Heroku Use the [Heroku Buildpack for Create React App](https://github.com/mars/create-react-app-buildpack). You can find instructions in [Deploying React with Zero Configuration](https://blog.heroku.com/deploying-react-with-zero-configuration). ### Surge Install the Surge CLI if you haven't already by running `npm install -g surge`. Run the `surge` command and log in you or create a new account. You just need to specify the *build* folder and your custom domain, and you are done. ```sh email: email@domain.com password: ******** project path: /path/to/project/build size: 7 files, 1.8 MB domain: create-react-app.surge.sh upload: [====================] 100%, eta: 0.0s propagate on CDN: [====================] 100% plan: Free users: email@domain.com IP Address: X.X.X.X Success! Project is published and running at create-react-app.surge.sh ``` Note that in order to support routers that use html5 `pushState` API, you may want to rename the `index.html` in your build folder to `200.html` before deploying to Surge. This [ensures that every URL falls back to that file](https://surge.sh/help/adding-a-200-page-for-client-side-routing). ### GitHub Pages >Note: this feature is available with `react-scripts@0.2.0` and higher. Open your `package.json` and add a `homepage` field: ```js "homepage": "http://myusername.github.io/my-app", ``` **The above step is important!** Create React App uses the `homepage` field to determine the root URL in the built HTML file. Now, whenever you run `npm run build`, you will see a cheat sheet with a sequence of commands to deploy to GitHub pages: ```sh git commit -am "Save local changes" git checkout -B gh-pages git add -f build git commit -am "Rebuild website" git filter-branch -f --prune-empty --subdirectory-filter build git push -f origin gh-pages git checkout - ``` You may copy and paste them, or put them into a custom shell script. You may also customize them for another hosting provider. Note that GitHub Pages doesn't support routers that use the HTML5 `pushState` history API under the hood (for example, React Router using `browserHistory`). This is because when there is a fresh page load for a url like `http://user.github.io/todomvc/todos/42`, where `/todos/42` is a frontend route, the GitHub Pages server returns 404 because it knows nothing of `/todos/42`. If you want to add a router to a project hosted on GitHub Pages, here are a couple of solutions: * You could switch from using HTML5 history API to routing with hashes. If you use React Router, you can switch to `hashHistory` for this effect, but the URL will be longer and more verbose (for example, `http://user.github.io/todomvc/#/todos/42?_k=yknaj`). [Read more](https://github.com/reactjs/react-router/blob/master/docs/guides/Histories.md#histories) about different history implementations in React Router. * Alternatively, you can use a trick to teach GitHub Pages to handle 404 by redirecting to your `index.html` page with a special redirect parameter. You would need to add a `404.html` file with the redirection code to the `build` folder before deploying your project, and you’ll need to add code handling the redirect parameter to `index.html`. You can find a detailed explanation of this technique [in this guide](https://github.com/rafrex/spa-github-pages). ## Something Missing? If you have ideas for more “How To” recipes that should be on this page, [let us know](https://github.com/facebookincubator/create-react-app/issues) or [contribute some!](https://github.com/facebookincubator/create-react-app/edit/master/template/README.md)
SOYJUN / FTP Implement Based On UDPThe aim of this assignment is to have you do UDP socket client / server programming with a focus on two broad aspects : Setting up the exchange between the client and server in a secure way despite the lack of a formal connection (as in TCP) between the two, so that ‘outsider’ UDP datagrams (broadcast, multicast, unicast - fortuitously or maliciously) cannot intrude on the communication. Introducing application-layer protocol data-transmission reliability, flow control and congestion control in the client and server using TCP-like ARQ sliding window mechanisms. The second item above is much more of a challenge to implement than the first, though neither is particularly trivial. But they are not tightly interdependent; each can be worked on separately at first and then integrated together at a later stage. Apart from the material in Chapters 8, 14 & 22 (especially Sections 22.5 - 22.7), and the experience you gained from the preceding assignment, you will also need to refer to the following : ioctl function (Chapter 17). get_ifi_info function (Section 17.6, Chapter 17). This function will be used by the server code to discover its node’s network interfaces so that it can bind all its interface IP addresses (see Section 22.6). ‘Race’ conditions (Section 20.5, Chapter 20) You also need a thorough understanding of how the TCP protocol implements reliable data transfer, flow control and congestion control. Chapters 17- 24 of TCP/IP Illustrated, Volume 1 by W. Richard Stevens gives a good overview of TCP. Though somewhat dated for some things (it was published in 1994), it remains, overall, a good basic reference. Overview This assignment asks you to implement a primitive file transfer protocol for Unix platforms, based on UDP, and with TCP-like reliability added to the transfer operation using timeouts and sliding-window mechanisms, and implementing flow and congestion control. The server is a concurrent server which can handle multiple clients simultaneously. A client gives the server the name of a file. The server forks off a child which reads directly from the file and transfers the contents over to the client using UDP datagrams. The client prints out the file contents as they come in, in order, with nothing missing and with no duplication of content, directly on to stdout (via the receiver sliding window, of course, but with no other intermediate buffering). The file to be transferred can be of arbitrary length, but its contents are always straightforward ascii text. As an aside let me mention that assuming the file contents ascii is not as restrictive as it sounds. We can always pretend, for example, that binary files are base64 encoded (“ASCII armor”). A real file transfer protocol would, of course, have to worry about transferring files between heterogeneous platforms with different file structure conventions and semantics. The sender would first have to transform the file into a platform-independent, protocol-defined, format (using, say, ASN.1, or some such standard), and the receiver would have to transform the received file into its platform’s native file format. This kind of thing can be fairly time consuming, and is certainly very tedious, to implement, with little educational value - it is not part of this assignment. Arguments for the server You should provide the server with an input file server.in from which it reads the following information, in the order shown, one item per line : Well-known port number for server. Maximum sending sliding-window size (in datagram units). You will not be handing in your server.in file. We shall create our own when we come to test your code. So it is important that you stick strictly to the file name and content conventions specified above. The same applies to the client.in input file below. Arguments for the client The client is to be provided with an input file client.in from which it reads the following information, in the order shown, one item per line : IP address of server (not the hostname). Well-known port number of server. filename to be transferred. Receiving sliding-window size (in datagram units). Random generator seed value. Probability p of datagram loss. This should be a real number in the range [ 0.0 , 1.0 ] (value 0.0 means no loss occurs; value 1.0 means all datagrams all lost). The mean µ, in milliseconds, for an exponential distribution controlling the rate at which the client reads received datagram payloads from its receive buffer. Operation Server starts up and reads its arguments from file server.in. As we shall see, when a client communicates with the server, the server will want to know what IP address that client is using to identify the server (i.e. , the destination IP address in the incoming datagram). Normally, this can be done relatively straightforwardly using the IP_RECVDESTADDR socket option, and picking up the information using the ancillary data (‘control information’) capability of the recvmsg function. Unfortunately, Solaris 2.10 does not support the IP_RECVDESTADDR option (nor, incidentally, does it support the msg_flags option in msghdr - see p.390). This considerably complicates things. In the absence of IP_RECVDESTADDR, what the server has to do as part of its initialization phase is to bind each IP address it has (and, simultaneously, its well-known port number, which it has read in from server.in) to a separate UDP socket. The code in Section 22.6, which uses the get_ifi_info function, shows you how to do that. However, there are important differences between that code and the version you want to implement. The code of Section 22.6 binds the IP addresses and forks off a child for each address that is bound to. We do not want to do that. Instead you should have an array of socket descriptors. For each IP address, create a new socket and bind the address (and well-known port number) to the socket without forking off child processes. Creating child processes comes later, when clients arrive. The code of Section 22.6 also attempts to bind broadcast addresses. We do not want to do this. It binds a wildcard IP address, which we certainly do not want to do either. We should bind strictly only unicast addresses (including the loopback address). The get_ifi_info function (which the code in Section 22.6 uses) has to be modified so that it also gets the network masks for the IP addresses of the node, and adds these to the information stored in the linked list of ifi_info structures (see Figure 17.5, p.471) it produces. As you go binding each IP address to a distinct socket, it will be useful for later processing to build your own array of structures, where a structure element records the following information for each socket : sockfd IP address bound to the socket network mask for the IP address subnet address (obtained by doing a bit-wise and between the IP address and its network mask) Report, in a ReadMe file which you hand in with your code, on the modifications you had to introduce to ensure that only unicast addresses are bound, and on your implementation of the array of structures described above. You should print out on stdout, with an appropriate message and appropriately formatted in dotted decimal notation, the IP address, network mask, and subnet address for each socket in your array of structures (you do not need to print the sockfd). The server now uses select to monitor the sockets it has created for incoming datagrams. When it returns from select, it must use recvfrom or recvmsg to read the incoming datagram (see 6. below). When a client starts, it first reads its arguments from the file client.in. The client checks if the server host is ‘local’ to its (extended) Ethernet. If so, all its communication to the server is to occur as MSG_DONTROUTE (or SO_DONTROUTE socket option). It determines if the server host is ‘local’ as follows. The first thing the client should do is to use the modified get_ifi_info function to obtain all of its IP addresses and associated network masks. Print out on stdout, in dotted decimal notation and with an appropriate message, the IP addresses and network masks obtained. In the following, IPserver designates the IP address the client will use to identify the server, and IPclient designates the IP address the client will choose to identify itself. The client checks whether the server is on the same host. If so, it should use the loopback address 127.0.0.1 for the server (i.e. , IPserver = 127.0.0.1). IPclient should also be set to the loopback address. Otherwise it proceeds as follows: IPserver is set to the IP address for the server in the client.in file. Given IPserver and the (unicast) IP addresses and network masks for the client returned by get_ifi_info in the linked list of ifi_info structures, you should be able to figure out if the server node is ‘local’ or not. This will be discussed in class; but let me just remind you here that you should use ‘longest prefix matching’ where applicable. If there are multiple client addresses, and the server host is ‘local’, the client chooses an IP address for itself, IPclient, which matches up as ‘local’ according to your examination above. If the server host is not ‘local’, then IPclient can be chosen arbitrarily. Print out on stdout the results of your examination, as to whether the server host is ‘local’ or not, as well as the IPclient and IPserver addresses selected. Note that this manner of determining whether the server is local or not is somewhat clumsy and ‘over-engineered’, and, as such, should be viewed more in the nature of a pedagogical exercise. Ideally, we would like to look up the server IP address(es) in the routing table (see Section 18.3). This requires that a routing socket be created, for which we need superuser privilege. Alternatively, we might want to dump out the routing table, using the sysctl function for example (see Section 18.4), and examine it directly. Unfortunately, Solaris 2.10 does not support sysctl. Furthermore, note that there is a slight problem with the address 130.245.1.123/24 assigned to compserv3 (see rightmost column of file hosts, and note that this particular compserv3 address “overlaps” with the 130.245.1.x/28 addresses in that same column assigned to compserv1, compserv2 & comserv4). In particular, if the client is running on compserv3 and the server on any of the other three compservs, and if that server node is also being identified to the client by its /28 (rather than its /24) address, then the client will get a “false positive” when it tests as to whether the server node is local or not. In other words, the client will deem the server node to be local, whereas in fact it should not be considered local. Because of this, it is perhaps best simply not to use compserv3 to run the client (but it is o.k. to use it to run the server). Finally, using MSG_DONTROUTE where possible would seem to gain us efficiency, in as much as the kernel does not need to consult the routing table for every datagram sent. But, in fact, that is not so. Recall that one effect of connect with UDP sockets is that routing information is obtained by the kernel at the time the connect is issued. That information is cached and used for subsequent sends from the connected socket (see p.255). The client now creates a UDP socket and calls bind on IPclient, with 0 as the port number. This will cause the kernel to bind an ephemeral port to the socket. After the bind, use the getsockname function (Section 4.10) to obtain IPclient and the ephemeral port number that has been assigned to the socket, and print that information out on stdout, with an appropriate message and appropriately formatted. The client connects its socket to IPserver and the well-known port number of the server. After the connect, use the getpeername function (Section 4.10) to obtain IPserver and the well-known port number of the server, and print that information out on stdout, with an appropriate message and appropriately formatted. The client sends a datagram to the server giving the filename for the transfer. This send needs to be backed up by a timeout in case the datagram is lost. Note that the incoming datagram from the client will be delivered to the server at the socket to which the destination IP address that the datagram is carrying has been bound. Thus, the server can obtain that address (it is, of course, IPserver) and thereby achieve what IP_RECVDESTADDR would have given us had it been available. Furthermore, the server process can obtain the IP address (this will, of course, be IPclient) and ephemeral port number of the client through the recvfrom or recvmsg functions. The server forks off a child process to handle the client. The server parent process goes back to the select to listen for new clients. Hereafter, and unless otherwise stated, whenever we refer to the ‘server’, we mean the server child process handling the client’s file transfer, not the server parent process. Typically, the first thing the server child would be expected to do is to close all sockets it ‘inherits’ from its parent. However, this is not the case with us. The server child does indeed close the sockets it inherited, but not the socket on which the client request arrived. It leaves that socket open for now. Call this socket the ‘listening’ socket. The server (child) then checks if the client host is local to its (extended) Ethernet. If so, all its communication to the client is to occur as MSG_DONTROUTE (or SO_DONTROUTE socket option). If IPserver (obtained in 5. above) is the loopback address, then we are done. Otherwise, the server has to proceed with the following step. Use the array of structures you built in 1. above, together with the addresses IPserver and IPclient to determine if the client is ‘local’. Print out on stdout the results of your examination, as to whether the client host is ‘local’ or not. The server (child) creates a UDP socket to handle file transfer to the client. Call this socket the ‘connection’ socket. It binds the socket to IPserver, with port number 0 so that its kernel assigns an ephemeral port. After the bind, use the getsockname function (Section 4.10) to obtain IPserver and the ephemeral port number that has been assigned to the socket, and print that information out on stdout, with an appropriate message and appropriately formatted. The server then connects this ‘connection’ socket to the client’s IPclient and ephemeral port number. The server now sends the client a datagram, in which it passes it the ephemeral port number of its ‘connection’ socket as the data payload of the datagram. This datagram is sent using the ‘listening’ socket inherited from its parent, otherwise the client (whose socket is connected to the server’s ‘listening’ socket at the latter’s well-known port number) will reject it. This datagram must be backed up by the ARQ mechanism, and retransmitted in the event of loss. Note that if this datagram is indeed lost, the client might well time out and retransmit its original request message (the one carrying the file name). In this event, you must somehow ensure that the parent server does not mistake this retransmitted request for a new client coming in, and spawn off yet another child to handle it. How do you do that? It is potentially more involved than it might seem. I will be discussing this in class, as well as ‘race’ conditions that could potentially arise, depending on how you code the mechanisms I present. When the client receives the datagram carrying the ephemeral port number of the server’s ‘connection’ socket, it reconnects its socket to the server’s ‘connection’ socket, using IPserver and the ephemeral port number received in the datagram (see p.254). It now uses this reconnected socket to send the server an acknowledgment. Note that this implies that, in the event of the server timing out, it should retransmit two copies of its ‘ephemeral port number’ message, one on its ‘listening’ socket and the other on its ‘connection’ socket (why?). When the server receives the acknowledgment, it closes the ‘listening’ socket it inherited from its parent. The server can now commence the file transfer through its ‘connection’ socket. The net effect of all these binds and connects at server and client is that no ‘outsider’ UDP datagram (broadcast, multicast, unicast - fortuitously or maliciously) can now intrude on the communication between server and client. Starting with the first datagram sent out, the client behaves as follows. Whenever a datagram arrives, or an ACK is about to be sent out (or, indeed, the initial datagram to the server giving the filename for the transfer), the client uses some random number generator function random() (initialized by the client.in argument value seed) to decide with probability p (another client.in argument value) if the datagram or ACK should be discarded by way of simulating transmission loss across the network. (I will briefly discuss in class how you do this.) Adding reliability to UDP The mechanisms you are to implement are based on TCP Reno. These include : Reliable data transmission using ARQ sliding-windows, with Fast Retransmit. Flow control via receiver window advertisements. Congestion control that implements : SlowStart Congestion Avoidance (‘Additive-Increase/Multiplicative Decrease’ – AIMD) Fast Recovery (but without the window-inflation aspect of Fast Recovery) Only some, and by no means all, of the details for these are covered below. The rest will be presented in class, especially those concerning flow control and TCP Reno’s congestion control mechanisms in general : Slow Start, Congestion Avoidance, Fast Retransmit and Fast Recovery. Implement a timeout mechanism on the sender (server) side. This is available to you from Stevens, Section 22.5 . Note, however, that you will need to modify the basic driving mechanism of Figure 22.7 appropriately since the situation at the sender side is not a repetitive cycle of send-receive, but rather a straightforward progression of send-send-send-send- . . . . . . . . . . . Also, modify the RTT and RTO mechanisms of Section 22.5 as specified below. I will be discussing the details of these modifications and the reasons for them in class. Modify function rtt_stop (Fig. 22.13) so that it uses integer arithmetic rather than floating point. This will entail your also having to modify some of the variable and function parameter declarations throughout Section 22.5 from float to int, as appropriate. In the unprrt.h header file (Fig. 22.10) set : RTT_RXTMIN to 1000 msec. (1 sec. instead of the current value 3 sec.) RTT_RXTMAX to 3000 msec. (3 sec. instead of the current value 60 sec.) RTT_MAXNREXMT to 12 (instead of the current value 3) In function rtt_timeout (Fig. 22.14), after doubling the RTO in line 86, pass its value through the function rtt_minmax of Fig. 22.11 (somewhat along the lines of what is done in line 77 of rtt_stop, Fig. 22.13). Finally, note that with the modification to integer calculation of the smoothed RTT and its variation, and given the small RTT values you will experience on the cs / sbpub network, these calculations should probably now be done on a millisecond or even microsecond scale (rather than in seconds, as is the case with Stevens’ code). Otherwise, small measured RTTs could show up as 0 on a scale of seconds, yielding a negative result when we subtract the smoothed RTT from the measured RTT (line 72 of rtt_stop, Fig. 22.13). Report the details of your modifications to the code of Section 22.5 in the ReadMe file which you hand in with your code. We need to have a sender sliding window mechanism for the retransmission of lost datagrams; and a receiver sliding window in order to ensure correct sequencing of received file contents, and some measure of flow control. You should implement something based on TCP Reno’s mechanisms, with cumulative acknowledgments, receiver window advertisements, and a congestion control mechanism I will explain in detail in class. For a reference on TCP’s mechanisms generally, see W. Richard Stevens, TCP/IP Illustrated, Volume 1 , especially Sections 20.2 - 20.4 of Chapter 20 , and Sections 21.1 - 21.8 of Chapter 21 . Bear in mind that our sequence numbers should count datagrams, not bytes as in TCP. Remember that the sender and receiver window sizes have to be set according to the argument values in client.in and server.in, respectively. Whenever the sender window becomes full and so ‘locks’, the server should print out a message to that effect on stdout. Similarly, whenever the receiver window ‘locks’, the client should print out a message on stdout. Be aware of the potential for deadlock when the receiver window ‘locks’. This situation is handled by having the receiver process send a duplicate ACK which acts as a window update when its window opens again (see Figure 20.3 and the discussion about it in TCP/IP Illustrated). However, this is not enough, because ACKs are not backed up by a timeout mechanism in the event they are lost. So we will also need to implement a persist timer driving window probes in the sender process (see Sections 22.1 & 22.2 in Chapter 22 of TCP/IP Illustrated). Note that you do not have to worry about the Silly Window Syndrome discussed in Section 22.3 of TCP/IP Illustrated since the receiver process consumes ‘full sized’ 512-byte messages from the receiver buffer (see 3. below). Report on the details of the ARQ mechanism you implemented in the ReadMe file you hand in. Indeed, you should report on all the TCP mechanisms you implemented in the ReadMe file, both the ones discussed here, and the ones I will be discussing in class. Make your datagram payload a fixed 512 bytes, inclusive of the file transfer protocol header (which must, at the very least, carry: the sequence number of the datagram; ACKs; and advertised window notifications). The client reads the file contents in its receive buffer and prints them out on stdout using a separate thread. This thread sits in a repetitive loop till all the file contents have been printed out, doing the following. It samples from an exponential distribution with mean µ milliseconds (read from the client.in file), sleeps for that number of milliseconds; wakes up to read and print all in-order file contents available in the receive buffer at that point; samples again from the exponential distribution; sleeps; and so on. The formula -1 × µ × ln( random( ) ) , where ln is the natural logarithm, yields variates from an exponential distribution with mean µ, based on the uniformly-distributed variates over ( 0 , 1 ) returned by random(). Note that you will need to implement some sort of mutual exclusion/semaphore mechanism on the client side so that the thread that sleeps and wakes up to consume from the receive buffer is not updating the state variables of the buffer at the same time as the main thread reading from the socket and depositing into the buffer is doing the same. Furthermore, we need to ensure that the main thread does not effectively monopolize the semaphore (and thus lock out for prolonged periods of time) the sleeping thread when the latter wakes up. See the textbook, Section 26.7, ‘Mutexes: Mutual Exclusion’, pp.697-701. You might also find Section 26.8, ‘Condition Variables’, pp.701-705, useful. You will need to devise some way by which the sender can notify the receiver when it has sent the last datagram of the file transfer, without the receiver mistaking that EOF marker as part of the file contents. (Also, note that the last data segment could be a “short” segment of less than 512 bytes – your client needs to be able to handle this correctly somehow.) When the sender receives an ACK for the last datagram of the transfer, the (child) server terminates. The parent server has to take care of cleaning up zombie children. Note that if we want a clean closing, the client process cannot simply terminate when the receiver ACKs the last datagram. This ACK could be lost, which would leave the (child) server process ‘hanging’, timing out, and retransmitting the last datagram. TCP attempts to deal with this problem by means of the TIME_WAIT state. You should have your receiver process behave similarly, sticking around in something akin to a TIME_WAIT state in case in case it needs to retransmit the ACK. In the ReadMe file you hand in, report on how you dealt with the issues raised here: sender notifying receiver of the last datagram, clean closing, and so on. Output Some of the output required from your program has been described in the section Operation above. I expect you to provide further output – clear, well-structured, well-laid-out, concise but sufficient and helpful – in the client and server windows by means of which we can trace the correct evolution of your TCP’s behaviour in all its intricacies : information (e.g., sequence number) on datagrams and acks sent and dropped, window advertisements, datagram retransmissions (and why : dup acks or RTO); entering/exiting Slow Start and Congestion Avoidance, ssthresh and cwnd values; sender and receiver windows locking/unlocking; etc., etc. . . . . The onus is on you to convince us that the TCP mechanisms you implemented are working correctly. Too many students do not put sufficient thought, creative imagination, time or effort into this. It is not the TA’s nor my responsibility to sit staring at an essentially blank screen, trying to summon up our paranormal psychology skills to figure out if your TCP implementation is really working correctly in all its very intricate aspects, simply because the transferred file seems to be printing o.k. in the client window. Nor is it our responsibility to strain our eyes and our patience wading through a mountain of obscure, ill-structured, hyper-messy, debugging-style output because, for example, your effort-conserving concept of what is ‘suitable’ is to dump your debugging output on us, relevant, irrelevant, and everything in between.
kiabuzz / CompressedLUTA tool to generate optimized hardware files for univariate functions.
Mdshobu / Liberty House Club Whitepaper# Liberty House Club **A Parallel Binance Chain to Enable Smart Contracts** _NOTE: This document is under development. Please check regularly for updates!_ ## Table of Contents - [Motivation](#motivation) - [Design Principles](#design-principles) - [Consensus and Validator Quorum](#consensus-and-validator-quorum) * [Proof of Staked Authority](#proof-of-staked-authority) * [Validator Quorum](#validator-quorum) * [Security and Finality](#security-and-finality) * [Reward](#reward) - [Token Economy](#token-economy) * [Native Token](#native-token) * [Other Tokens](#other-tokens) - [Cross-Chain Transfer and Communication](#cross-chain-transfer-and-communication) * [Cross-Chain Transfer](#cross-chain-transfer) * [BC to BSC Architecture](#bc-to-bsc-architecture) * [BSC to BC Architecture](#bsc-to-bc-architecture) * [Timeout and Error Handling](#timeout-and-error-handling) * [Cross-Chain User Experience](#cross-chain-user-experience) * [Cross-Chain Contract Event](#cross-chain-contract-event) - [Staking and Governance](#staking-and-governance) * [Staking on BC](#staking-on-bc) * [Rewarding](#rewarding) * [Slashing](#slashing) - [Relayers](#relayers) * [BSC Relayers](#bsc-relayers) * [Oracle Relayers](#oracle-relayers) - [Outlook](#outlook) # Motivation After its mainnet community [launch](https://www.binance.com/en/blog/327334696200323072/Binance-DEX-Launches-on-Binance-Chain-Invites-Further-Community-Development) in April 2019, [Binance Chain](https://www.binance.org) has exhibited its high speed and large throughput design. Binance Chain’s primary focus, its native [decentralized application](https://en.wikipedia.org/wiki/Decentralized_application) (“dApp”) [Binance DEX](https://www.binance.org/trade), has demonstrated its low-latency matching with large capacity headroom by handling millions of trading volume in a short time. Flexibility and usability are often in an inverse relationship with performance. The concentration on providing a convenient digital asset issuing and trading venue also brings limitations. Binance Chain's most requested feature is the programmable extendibility, or simply the [Smart Contract](https://en.wikipedia.org/wiki/Smart_contract) and Virtual Machine functions. Digital asset issuers and owners struggle to add new decentralized features for their assets or introduce any sort of community governance and activities. Despite this high demand for adding the Smart Contract feature onto Binance Chain, it is a hard decision to make. The execution of a Smart Contract may slow down the exchange function and add non-deterministic factors to trading. If that compromise could be tolerated, it might be a straightforward idea to introduce a new Virtual Machine specification based on [Tendermint](https://tendermint.com/core/), based on the current underlying consensus protocol and major [RPC](https://docs.binance.org/api-reference/node-rpc.html) implementation of Binance Chain. But all these will increase the learning requirements for all existing dApp communities, and will not be very welcomed. We propose a parallel blockchain of the current Binance Chain to retain the high performance of the native DEX blockchain and to support a friendly Smart Contract function at the same time. # Design Principles After the creation of the parallel blockchain into the Binance Chain ecosystem, two blockchains will run side by side to provide different services. The new parallel chain will be called “**Binance Smart Chain**” (short as “**BSC**” for the below sections), while the existing mainnet remains named “**Binance Chain**” (short as “**BC**” for the below sections). Here are the design principles of **BSC**: 1. **Standalone Blockchain**: technically, BSC is a standalone blockchain, instead of a layer-2 solution. Most BSC fundamental technical and business functions should be self-contained so that it can run well even if the BC stopped for a short period. 2. **Ethereum Compatibility**: The first practical and widely-used Smart Contract platform is Ethereum. To take advantage of the relatively mature applications and community, BSC chooses to be compatible with the existing Ethereum mainnet. This means most of the **dApps**, ecosystem components, and toolings will work with BSC and require zero or minimum changes; BSC node will require similar (or a bit higher) hardware specification and skills to run and operate. The implementation should leave room for BSC to catch up with further Ethereum upgrades. 3. **Staking Involved Consensus and Governance**: Staking-based consensus is more environmentally friendly and leaves more flexible option to the community governance. Expectedly, this consensus should enable better network performance over [proof-of-work](https://en.wikipedia.org/wiki/Proof_of_work) blockchain system, i.e., faster blocking time and higher transaction capacity. 4. **Native Cross-Chain Communication**: both BC and BSC will be implemented with native support for cross-chain communication among the two blockchains. The communication protocol should be bi-directional, decentralized, and trustless. It will concentrate on moving digital assets between BC and BSC, i.e., [BEP2](https://github.com/binance-chain/BEPs/blob/master/BEP2.md) tokens, and eventually, other BEP tokens introduced later. The protocol should care for the minimum of other items stored in the state of the blockchains, with only a few exceptions. # Consensus and Validator Quorum Based on the above design principles, the consensus protocol of BSC is to fulfill the following goals: 1. Blocking time should be shorter than Ethereum network, e.g. 5 seconds or even shorter. 2. It requires limited time to confirm the finality of transactions, e.g. around 1-min level or shorter. 3. There is no inflation of native token: BNB, the block reward is collected from transaction fees, and it will be paid in BNB. 4. It is compatible with Ethereum system as much as possible. 5. It allows modern [proof-of-stake](https://en.wikipedia.org/wiki/Proof_of_stake) blockchain network governance. ## Proof of Staked Authority Although Proof-of-Work (PoW) has been recognized as a practical mechanism to implement a decentralized network, it is not friendly to the environment and also requires a large size of participants to maintain the security. Ethereum and some other blockchain networks, such as [MATIC Bor](https://github.com/maticnetwork/bor), [TOMOChain](https://tomochain.com/), [GoChain](https://gochain.io/), [xDAI](https://xdai.io/), do use [Proof-of-Authority(PoA)](https://en.wikipedia.org/wiki/Proof_of_authority) or its variants in different scenarios, including both testnet and mainnet. PoA provides some defense to 51% attack, with improved efficiency and tolerance to certain levels of Byzantine players (malicious or hacked). It serves as an easy choice to pick as the fundamentals. Meanwhile, the PoA protocol is most criticized for being not as decentralized as PoW, as the validators, i.e. the nodes that take turns to produce blocks, have all the authorities and are prone to corruption and security attacks. Other blockchains, such as EOS and Lisk both, introduce different types of [Delegated Proof of Stake (DPoS)](https://en.bitcoinwiki.org/wiki/DPoS) to allow the token holders to vote and elect the validator set. It increases the decentralization and favors community governance. BSC here proposes to combine DPoS and PoA for consensus, so that: 1. Blocks are produced by a limited set of validators 2. Validators take turns to produce blocks in a PoA manner, similar to [Ethereum’s Clique](https://eips.ethereum.org/EIPS/eip-225) consensus design 3. Validator set are elected in and out based on a staking based governance ## Validator Quorum In the genesis stage, a few trusted nodes will run as the initial Validator Set. After the blocking starts, anyone can compete to join as candidates to elect as a validator. The staking status decides the top 21 most staked nodes to be the next validator set, and such an election will repeat every 24 hours. **BNB** is the token used to stake for BSC. In order to remain as compatible as Ethereum and upgradeable to future consensus protocols to be developed, BSC chooses to rely on the **BC** for staking management (Please refer to the below “[Staking and Governance](#staking-and-governance)” section). There is a **dedicated staking module for BSC on BC**. It will accept BSC staking from BNB holders and calculate the highest staked node set. Upon every UTC midnight, BC will issue a verifiable `ValidatorSetUpdate` cross-chain message to notify BSC to update its validator set. While producing further blocks, the existing BSC validators check whether there is a `ValidatorSetUpdate` message relayed onto BSC periodically. If there is, they will update the validator set after an **epoch period**, i.e. a predefined number of blocking time. For example, if BSC produces a block every 5 seconds, and the epoch period is 240 blocks, then the current validator set will check and update the validator set for the next epoch in 1200 seconds (20 minutes). ## Security and Finality Given there are more than ½\*N+1 validators are honest, PoA based networks usually work securely and properly. However, there are still cases where certain amount Byzantine validators may still manage to attack the network, e.g. through the “[Clone Attack](https://arxiv.org/pdf/1902.10244.pdf)”. To secure as much as BC, BSC users are encouraged to wait until receiving blocks sealed by more than ⅔\*N+1 different validators. In that way, the BSC can be trusted at a similar security level to BC and can tolerate less than ⅓\*N Byzantine validators. With 21 validators, if the block time is 5 seconds, the ⅔\*N+1 different validator seals will need a time period of (⅔\*21+1)*5 = 75 seconds. Any critical applications for BSC may have to wait for ⅔\*N+1 to ensure a relatively secure finality. However, besides such arrangement, BSC does introduce **Slashing** logic to penalize Byzantine validators for **double signing** or **inavailability**, which will be covered in the “Staking and Governance” section later. This Slashing logic will expose the malicious validators in a very short time and make the “Clone Attack” very hard or extremely non-beneficial to execute. With this enhancement, ½\*N+1 or even fewer blocks are enough as confirmation for most transactions. ## Reward All the BSC validators in the current validator set will be rewarded with transaction **fees in BNB**. As BNB is not an inflationary token, there will be no mining rewards as what Bitcoin and Ethereum network generate, and the gas fee is the major reward for validators. As BNB is also utility tokens with other use cases, delegators and validators will still enjoy other benefits of holding BNB. The reward for validators is the fees collected from transactions in each block. Validators can decide how much to give back to the delegators who stake their BNB to them, in order to attract more staking. Every validator will take turns to produce the blocks in the same probability (if they stick to 100% liveness), thus, in the long run, all the stable validators may get a similar size of the reward. Meanwhile, the stakes on each validator may be different, so this brings a counter-intuitive situation that more users trust and delegate to one validator, they potentially get less reward. So rational delegators will tend to delegate to the one with fewer stakes as long as the validator is still trustful (insecure validator may bring slashable risk). In the end, the stakes on all the validators will have less variation. This will actually prevent the stake concentration and “winner wins forever” problem seen on some other networks. Some parts of the gas fee will also be rewarded to relayers for Cross-Chain communication. Please refer to the “[Relayers](#relayers)” section below. # Token Economy BC and BSC share the same token universe for BNB and BEP2 tokens. This defines: 1. The same token can circulate on both networks, and flow between them bi-directionally via a cross-chain communication mechanism. 2. The total circulation of the same token should be managed across the two networks, i.e. the total effective supply of a token should be the sum of the token’s total effective supply on both BSC and BC. 3. The tokens can be initially created on BSC in a similar format as ERC20 token standard, or on BC as a BEP2, then created on the other. There are native ways on both networks to link the two and secure the total supply of the token. ## Native Token BNB will run on BSC in the same way as ETH runs on Ethereum so that it remains as “native token” for both BSC and BC. This means, in addition to BNB is used to pay most of the fees on Binance Chain and Binance DEX, BNB will be also used to: 1. pay “fees“ to deploy smart contracts on BSC 2. stake on selected BSC validators, and get corresponding rewards 3. perform cross-chain operations, such as transfer token assets across BC and BSC ### Seed Fund Certain amounts of BNB will be burnt on BC and minted on BSC during its genesis stage. This amount is called “Seed Fund” to circulate on BSC after the first block, which will be dispatched to the initial BC-to-BSC Relayer(described in later sections) and initial validator set introduced at genesis. These BNBs are used to pay transaction fees in the early stage to transfer more BNB from BC onto BSC via the cross-chain mechanism. The BNB cross-chain transfer is discussed in a later section, but for BC to BSC transfer, it is generally to lock BNB on BC from the source address of the transfer to a system-controlled address and unlock the corresponding amount from special contract to the target address of the transfer on BSC, or reversely, when transferring from BSC to BC, it is to lock BNB from the source address on BSC into a special contract and release locked amount on BC from the system address to the target address. The logic is related to native code on BC and a series of smart contracts on BSC. ## Other Tokens BC supports BEP2 tokens and upcoming [BEP8 tokens](https://github.com/binance-chain/BEPs/pull/69), which are native assets transferrable and tradable (if listed) via fast transactions and sub-second finality. Meanwhile, as BSC is Ethereum compatible, it is natural to support ERC20 tokens on BSC, which here is called “**BEP2E**” (with the real name to be introduced by the future BEPs,it potentially covers BEP8 as well). BEP2E may be “Enhanced” by adding a few more methods to expose more information, such as token denomination, decimal precision definition and the owner address who can decide the Token Binding across the chains. BSC and BC work together to ensure that one token can circulate in both formats with confirmed total supply and be used in different use cases. ### Token Binding BEP2 tokens will be extended to host a new attribute to associate the token with a BSC BEP2E token contract, called “**Binder**”, and this process of association is called “**Token Binding**”. Token Binding can happen at any time after BEP2 and BEP2E are ready. The token owners of either BEP2 or BEP2E don’t need to bother about the Binding, until before they really want to use the tokens on different scenarios. Issuers can either create BEP2 first or BEP2E first, and they can be bound at a later time. Of course, it is encouraged for all the issuers of BEP2 and BEP2E to set the Binding up early after the issuance. A typical procedure to bind the BEP2 and BEP2E will be like the below: 1. Ensure both the BEP2 token and the BEP2E token both exist on each blockchain, with the same total supply. BEP2E should have 3 more methods than typical ERC20 token standard: * symbol(): get token symbol * decimals(): get the number of the token decimal digits * owner(): get **BEP2E contract owner’s address.** This value should be initialized in the BEP2E contract constructor so that the further binding action can verify whether the action is from the BEP2E owner. 2. Decide the initial circulation on both blockchains. Suppose the total supply is *S*, and the expected initial circulating supply on BC is *K*, then the owner should lock S-K tokens to a system controlled address on BC. 3. Equivalently, *K* tokens is locked in the special contract on BSC, which handles major binding functions and is named as **TokenHub**. The issuer of the BEP2E token should lock the *K* amount of that token into TokenHub, resulting in *S-K* tokens to circulate on BSC. Thus the total circulation across 2 blockchains remains as *S*. 4. The issuer of BEP2 token sends the bind transaction on BC. Once the transaction is executed successfully after proper verification: * It transfers *S-K* tokens to a system-controlled address on BC. * A cross-chain bind request package will be created, waiting for Relayers to relay. 5. BSC Relayers will relay the cross-chain bind request package into **TokenHub** on BSC, and the corresponding request and information will be stored into the contract. 6. The contract owner and only the owner can run a special method of TokenHub contract, `ApproveBind`, to verify the binding request to mark it as a success. It will confirm: * the token has not been bound; * the binding is for the proper symbol, with proper total supply and decimal information; * the proper lock are done on both networks; 10. Once the `ApproveBind` method has succeeded, TokenHub will mark the two tokens are bounded and share the same circulation on BSC, and the status will be propagated back to BC. After this final confirmation, the BEP2E contract address and decimals will be written onto the BEP2 token as a new attribute on BC, and the tokens can be transferred across the two blockchains bidirectionally. If the ApproveBind fails, the failure event will also be propagated back to BC to release the locked tokens, and the above steps can be re-tried later. # Cross-Chain Transfer and Communication Cross-chain communication is the key foundation to allow the community to take advantage of the dual chain structure: * users are free to create any tokenization, financial products, and digital assets on BSC or BC as they wish * the items on BSC can be manually and programmingly traded and circulated in a stable, high throughput, lighting fast and friendly environment of BC * users can operate these in one UI and tooling ecosystem. ## Cross-Chain Transfer The cross-chain transfer is the key communication between the two blockchains. Essentially the logic is: 1. the `transfer-out` blockchain will lock the amount from source owner addresses into a system controlled address/contracts; 2. the `transfer-in` blockchain will unlock the amount from the system controlled address/contracts and send it to target addresses. The cross-chain transfer package message should allow the BSC Relayers and BC **Oracle Relayers** to verify: 1. Enough amount of token assets are removed from the source address and locked into a system controlled addresses/contracts on the source blockchain. And this can be confirmed on the target blockchain. 2. Proper amounts of token assets are released from a system controlled addresses/contracts and allocated into target addresses on the target blockchain. If this fails, it can be confirmed on source blockchain, so that the locked token can be released back (may deduct fees). 3. The sum of the total circulation of the token assets across the 2 blockchains are not changed after this transfer action completes, no matter if the transfer succeeds or not.  The architecture of cross-chain communication is as in the above diagram. To accommodate the 2 heteroid systems, communication handling is different in each direction. ## BC to BSC Architecture BC is a Tendermint-based, instant finality blockchain. Validators with at least ⅔\*N+1 of the total voting power will co-sign each block on the chain. So that it is practical to verify the block transactions and even the state value via **Block Header** and **Merkle Proof** verification. This has been researched and implemented as “**Light-Client Protocol**”, which are intensively discussed in [the Ethereum](https://github.com/ethereum/wiki/wiki/Light-client-protocol) community, studied and implemented for [Cosmos inter-chain communication](https://github.com/cosmos/ics/blob/a4173c91560567bdb7cc9abee8e61256fc3725e9/spec/ics-007-tendermint-client/README.md). BC-to-BSC communication will be verified in an “**on-chain light client**” implemented via BSC **Smart Contracts** (some of them may be **“pre-compiled”**). After some transactions and state change happen on BC, if a transaction is defined to trigger cross-chain communication,the Cross-chain “**package**” message will be created and **BSC Relayers** will pass and submit them onto BSC as data into the "build-in system contracts". The build-in system contracts will verify the package and execute the transactions if it passes the verification. The verification will be guaranteed with the below design: 1. BC blocking status will be synced to the light client contracts on BSC from time to time, via block header and pre-commits, for the below information: * block and app hash of BC that are signed by validators * current validatorset, and validator set update 2. the key-value from the blockchain state will be verified based on the Merkle Proof and information from above #1. After confirming the key-value is accurate and trustful, the build-in system contracts will execute the actions corresponding to the cross-chain packages. Some examples of such packages that can be created for BC-to-BSC are: 1. Bind: bind the BEP2 tokens and BEP2E 2. Transfer: transfer tokens after binding, this means the circulation will decrease (be locked) from BC and appear in the target address balance on BSC 3. Error Handling: to handle any timeout/failure event for BSC-to-BC communication 4. Validatorset update of BSC To ensure no duplication, proper message sequence and timely timeout, there is a “Channel” concept introduced on BC to manage any types of the communication. For relayers, please also refer to the below “Relayers” section. ## BSC to BC Architecture BSC uses Proof of Staked Authority consensus protocol, which has a chance to fork and requires confirmation of more blocks. One block only has the signature of one validator, so that it is not easy to rely on one block to verify data from BSC. To take full advantage of validator quorum of BC, an idea similar to many [Bridge ](https://github.com/poanetwork/poa-bridge)or Oracle blockchains is adopted: 1. The cross-chain communication requests from BSC will be submitted and executed onto BSC as transactions. The execution of the transanction wil emit `Events`, and such events can be observed and packaged in certain “**Oracle**” onto BC. Instead of Block Headers, Hash and Merkle Proof, this type of “Oracle” package directly contains the cross-chain information for actions, such as sender, receiver and amount for transfer. 2. To ensure the security of the Oracle, the validators of BC will form anothe quorum of “**Oracle Relayers**”. Each validator of the BC should run a **dedicated process** as the Oracle Relayer. These Oracle Relayers will submit and vote for the cross-chain communication package, like Oracle, onto BC, using the same validator keys. Any package signed by more than ⅔\*N+1 Oracle Relayers’ voting power is as secure as any block signed by ⅔\*N+1 of the same quorum of validators’ voting power. By using the same validator quorum, it saves the light client code on BC and continuous block updates onto BC. Such Oracles also have Oracle IDs and types, to ensure sequencing and proper error handling. ## Timeout and Error Handling There are scenarios that the cross-chain communication fails. For example, the relayed package cannot be executed on BSC due to some coding bug in the contracts. **Timeout and error handling logics are** used in such scenarios. For the recognizable user and system errors or any expected exceptions, the two networks should heal themselves. For example, when BC to BSC transfer fails, BSC will issue a failure event and Oracle Relayers will execute a refund on BC; when BSC to BC transfer fails, BC will issue a refund package for Relayer to relay in order to unlock the fund. However, unexpected error or exception may still happen on any step of the cross-chain communication. In such a case, the Relayers and Oracle Relayers will discover that the corresponding cross-chain channel is stuck in a particular sequence. After a Timeout period, the Relayers and Oracle Relayers can request a “SkipSequence” transaction, the stuck sequence will be marked as “Unexecutable”. A corresponding alerts will be raised, and the community has to discuss how to handle this scenario, e.g. payback via the sponsor of the validators, or event clear the fund during next network upgrade. ## Cross-Chain User Experience Ideally, users expect to use two parallel chains in the same way as they use one single chain. It requires more aggregated transaction types to be added onto the cross-chain communication to enable this, which will add great complexity, tight coupling, and maintenance burden. Here BC and BSC only implement the basic operations to enable the value flow in the initial launch and leave most of the user experience work to client side UI, such as wallets. E.g. a great wallet may allow users to sell a token directly from BSC onto BC’s DEX order book, in a secure way. ## Cross-Chain Contract Event Cross-Chain Contract Event (CCCE) is designed to allow a smart contract to trigger cross-chain transactions, directly through the contract code. This becomes possible based on: 1. Standard system contracts can be provided to serve operations callable by general smart contracts; 2. Standard events can be emitted by the standard contracts; 3. Oracle Relayers can capture the standard events, and trigger the corresponding cross-chain operations; 4. Dedicated, code-managed address (account) can be created on BC and accessed by the contracts on the BSC, here it is named as **“Contract Address on BC” (CAoB)**. Several standard operations are implemented: 1. BSC to BC transfer: this is implemented in the same way as normal BSC to BC transfer, by only triggered via standard contract. The fund can be transferred to any addresses on BC, including the corresponding CAoB of the transfer originating contract. 2. Transfer on BC: this is implemented as a special cross-chain transfer, while the real transfer is from **CAoB** to any other address (even another CAoB). 3. BC to BSC transfer: this is implemented as two-pass cross-chain communication. The first is triggered by the BSC contract and propagated onto BC, and then in the second pass, BC will start a normal BC to BSC cross-chain transfer, from **CAoB** to contract address on BSC. A special note should be paid on that the BSC contract only increases balance upon any transfer coming in on the second pass, and the error handling in the second pass is the same as the normal BC to BSC transfer. 4. IOC (Immediate-Or-Cancel) Trade Out: the primary goal of transferring assets to BC is to trade. This event will instruct to trade a certain amount of an asset in CAoB into another asset as much as possible and transfer out all the results, i.e. the left the source and the traded target tokens of the trade, back to BSC. BC will handle such relayed events by sending an “Immediate-Or-Cancel”, i.e. IOC order onto the trading pairs, once the next matching finishes, the result will be relayed back to BSC, which can be in either one or two assets. 5. Auction Trade Out: Such event will instruct BC to send an auction order to trade a certain amount of an asset in **CAoB** into another asset as much as possible and transfer out all the results back to BSC at the end of the auction. Auction function is upcoming on BC. There are some details for the Trade Out: 1. both can have a limit price (absolute or relative) for the trade; 2. the end result will be written as cross-chain packages to relay back to BSC; 3. cross-chain communication fees may be charged from the asset transferred back to BSC; 4. BSC contract maintains a mirror of the balance and outstanding orders on CAoB. No matter what error happens during the Trade Out, the final status will be propagated back to the originating contract and clear its internal state. With the above features, it simply adds the cross-chain transfer and exchange functions with high liquidity onto all the smart contracts on BSC. It will greatly add the application scenarios on Smart Contract and dApps, and make 1 chain +1 chain > 2 chains. # Staking and Governance Proof of Staked Authority brings in decentralization and community involvement. Its core logic can be summarized as the below. You may see similar ideas from other networks, especially Cosmos and EOS. 1. Token holders, including the validators, can put their tokens “**bonded**” into the stake. Token holders can **delegate** their tokens onto any validator or validator candidate, to expect it can become an actual validator, and later they can choose a different validator or candidate to **re-delegate** their tokens<sup>1</sup>. 2. All validator candidates will be ranked by the number of bonded tokens on them, and the top ones will become the real validators. 3. Validators can share (part of) their blocking reward with their delegators. 4. Validators can suffer from “**Slashing**”, a punishment for their bad behaviors, such as double sign and/or instability. 5. There is an “**unbonding period**” for validators and delegators so that the system makes sure the tokens remain bonded when bad behaviors are caught, the responsible will get slashed during this period. ## Staking on BC Ideally, such staking and reward logic should be built into the blockchain, and automatically executed as the blocking happens. Cosmos Hub, who shares the same Tendermint consensus and libraries with Binance Chain, works in this way. BC has been preparing to enable staking logic since the design days. On the other side, as BSC wants to remain compatible with Ethereum as much as possible, it is a great challenge and efforts to implement such logic on it. This is especially true when Ethereum itself may move into a different Proof of Stake consensus protocol in a short (or longer) time. In order to keep the compatibility and reuse the good foundation of BC, the staking logic of BSC is implemented on BC: 1. The staking token is BNB, as it is a native token on both blockchains anyway 2. The staking, i.e. token bond and delegation actions and records for BSC, happens on BC. 3. The BSC validator set is determined by its staking and delegation logic, via a staking module built on BC for BSC, and propagated every day UTC 00:00 from BC to BSC via Cross-Chain communication. 4. The reward distribution happens on BC around every day UTC 00:00. ## Rewarding Both the validator update and reward distribution happen every day around UTC 00:00. This is to save the cost of frequent staking updates and block reward distribution. This cost can be significant, as the blocking reward is collected on BSC and distributed on BC to BSC validators and delegators. (Please note BC blocking fees will remain rewarding to BC validators only.) A deliberate delay is introduced here to make sure the distribution is fair: 1. The blocking reward will not be sent to validator right away, instead, they will be distributed and accumulated on a contract; 2. Upon receiving the validator set update into BSC, it will trigger a few cross-chain transfers to transfer the reward to custody addresses on the corresponding validators. The custody addresses are owned by the system so that the reward cannot be spent until the promised distribution to delegators happens. 3. In order to make the synchronization simpler and allocate time to accommodate slashing, the reward for N day will be only distributed in N+2 days. After the delegators get the reward, the left will be transferred to validators’ own reward addresses. ## Slashing Slashing is part of the on-chain governance, to ensure the malicious or negative behaviors are punished. BSC slash can be submitted by anyone. The transaction submission requires **slash evidence** and cost fees but also brings a larger reward when it is successful. So far there are two slashable cases. ### Double Sign It is quite a serious error and very likely deliberate offense when a validator signs more than one block with the same height and parent block. The reference protocol implementation should already have logic to prevent this, so only the malicious code can trigger this. When Double Sign happens, the validator should be removed from the Validator **Set** right away. Anyone can submit a slash request on BC with the evidence of Double Sign of BSC, which should contain the 2 block headers with the same height and parent block, sealed by the offending validator. Upon receiving the evidence, if the BC verifies it to be valid: 1. The validator will be removed from validator set by an instance BSC validator set update Cross-Chain update; 2. A predefined amount of BNB would be slashed from the **self-delegated** BNB of the validator; Both validator and its delegators will not receive the staking rewards. 3. Part of the slashed BNB will allocate to the submitter’s address, which is a reward and larger than the cost of submitting slash request transaction 4. The rest of the slashed BNB will allocate to the other validators’ custody addresses, and distributed to all delegators in the same way as blocking reward. ### Inavailability The liveness of BSC relies on everyone in the Proof of Staked Authority validator set can produce blocks timely when it is their turn. Validators can miss their turn due to any reason, especially problems in their hardware, software, configuration or network. This instability of the operation will hurt the performance and introduce more indeterministic into the system. There can be an internal smart contract responsible for recording the missed blocking metrics of each validator. Once the metrics are above the predefined threshold, the blocking reward for validator will not be relayed to BC for distribution but shared with other better validators. In such a way, the poorly-operating validator should be gradually voted out of the validator set as their delegators will receive less or none reward. If the metrics remain above another higher level of threshold, the validator will be dropped from the rotation, and this will be propagated back to BC, then a predefined amount of BNB would be slashed from the **self-delegated** BNB of the validator. Both validators and delegators will not receive their staking rewards. ### Governance Parameters There are many system parameters to control the behavior of the BSC, e.g. slash amount, cross-chain transfer fees. All these parameters will be determined by BSC Validator Set together through a proposal-vote process based on their staking. Such the process will be carried on BC, and the new parameter values will be picked up by corresponding system contracts via a cross-chain communication. # Relayers Relayers are responsible to submit Cross-Chain Communication Packages between the two blockchains. Due to the heterogeneous parallel chain structure, two different types of Relayers are created. ## BSC Relayers Relayers for BC to BSC communication referred to as “**BSC Relayers**”, or just simply “Relayers”. Relayer is a standalone process that can be run by anyone, and anywhere, except that Relayers must register themselves onto BSC and deposit a certain refundable amount of BNB. Only relaying requests from the registered Relayers will be accepted by BSC. The package they relay will be verified by the on-chain light client on BSC. The successful relay needs to pass enough verification and costs gas fees on BSC, and thus there should be incentive reward to encourage the community to run Relayers. ### Incentives There are two major communication types: 1. Users triggered Operations, such as `token bind` or `cross chain transfer`. Users must pay additional fee to as relayer reward. The reward will be shared with the relayers who sync the referenced blockchain headers. Besides, the reward won't be paid the relayers' accounts directly. A reward distribution mechanism will be brought in to avoid monopolization. 2. System Synchronization, such as delivering `refund package`(caused by failures of most oracle relayers), special blockchain header synchronization(header contains BC validatorset update), BSC staking package. System reward contract will pay reward to relayers' accounts directly. If some Relayers have faster networks and better hardware, they can monopolize all the package relaying and leave no reward to others. Thus fewer participants will join for relaying, which encourages centralization and harms the efficiency and security of the network. Ideally, due to the decentralization and dynamic re-election of BSC validators, one Relayer can hardly be always the first to relay every message. But in order to avoid the monopolization further, the rewarding economy is also specially designed to minimize such chance: 1. The reward for Relayers will be only distributed in batches, and one batch will cover a number of successful relayed packages. 2. The reward a Relayer can get from a batch distribution is not linearly in proportion to their number of successful relayed packages. Instead, except the first a few relays, the more a Relayer relays during a batch period, the less reward it will collect. ## Oracle Relayers Relayers for BSC to BC communication are using the “Oracle” model, and so-called “**Oracle Relayers**”. Each of the validators must, and only the ones of the validator set, run Oracle Relayers. Each Oracle Relayer watches the blockchain state change. Once it catches Cross-Chain Communication Packages, it will submit to vote for the requests. After Oracle Relayers from ⅔ of the voting power of BC validators vote for the changes, the cross-chain actions will be performed. Oracle Replayers should wait for enough blocks to confirm the finality on BSC before submitting and voting for the cross-chain communication packages onto BC. The cross-chain fees will be distributed to BC validators together with the normal BC blocking rewards. Such oracle type relaying depends on all the validators to support. As all the votes for the cross-chain communication packages are recorded on the blockchain, it is not hard to have a metric system to assess the performance of the Oracle Relayers. The poorest performer may have their rewards clawed back via another Slashing logic introduced in the future. # Outlook It is hard to conclude for Binance Chain, as it has never stopped evolving. The dual-chain strategy is to open the gate for users to take advantage of the fast transferring and trading on one side, and flexible and extendable programming on the other side, but it will be one stop along the development of Binance Chain. Here below are the topics to look into so as to facilitate the community better for more usability and extensibility: 1. Add different digital asset model for different business use cases 2. Enable more data feed, especially DEX market data, to be communicated from Binance DEX to BSC 3. Provide interface and compatibility to integrate with Ethereum, including its further upgrade, and other blockchain 4. Improve client side experience to manage wallets and use blockchain more conveniently ------ [1]: BNB business practitioners may provide other benefits for BNB delegators, as they do now for long term BNB holders.
SOYJUN / Implement ODR ProtocolOverview For this assignment you will be developing and implementing : An On-Demand shortest-hop Routing (ODR) protocol for networks of fixed but arbitrary and unknown connectivity, using PF_PACKET sockets. The implementation is based on (a simplified version of) the AODV algorithm. Time client and server applications that send requests and replies to each other across the network using ODR. An API you will implement using Unix domain datagram sockets enables applications to communicate with the ODR mechanism running locally at their nodes. I shall be discussing the assignment in class on Wednesday, October 29, and Monday, November 3. The following should prove useful reference material for the assignment : Sections 15.1, 15.2, 15.4 & 15.6, Chapter 15, on Unix domain datagram sockets. PF_PACKET(7) from the Linux manual pages. You might find these notes made by a past CSE 533 student useful. Also, the following link http://www.pdbuchan.com/rawsock/rawsock.html contains useful code samples that use PF_PACKET sockets (as well as other code samples that use raw IP sockets which you do not need for this assignment, though you will be using these types of sockets for Assignment 4). Charles E. Perkins & Elizabeth M. Royer. “Ad-hoc On-Demand Distance Vector Routing.” Proceedings of the 2nd IEEE Workshop on Mobile Computing Systems and Applications, New Orleans, Louisiana, February 1999, pp. 90 - 100. The VMware environment minix.cs.stonybrook.edu is a Linux box running VMware. A cluster of ten Linux virtual machines, called vm1 through vm10, on which you can gain access as root and run your code have been created on minix. See VMware Environment Hosts for further details. VMware instructions takes you to a page that explains how to use the system. The ten virtual machines have been configured into a small virtual intranet of Ethernet LANs whose topology is (in principle) unknown to you. There is a course account cse533 on node minix, with home directory /users/cse533. In there, you will find a subdirectory Stevens/unpv13e , exactly as you are used to having on the cs system. You should develop your source code and makefiles for handing in accordingly. You will be handing in your source code on the minix node. Note that you do not need to link against the socket library (-lsocket) in Linux. The same is true for -lnsl and -lresolv. For example, take a look at how the LIBS variable is defined for Solaris, in /home/courses/cse533/Stevens/unpv13e_solaris2.10/Make.defines (on compserv1, say) : LIBS = ../libunp.a -lresolv -lsocket -lnsl -lpthread But if you take a look at Make.defines on minix (/users/cse533/Stevens/unpv13e/Make.defines) you will find only: LIBS = ../libunp.a -lpthread The nodes vm1 , . . . . . , vm10 are all multihomed : each has two (or more) interfaces. The interface ‘eth0 ’ should be completely ignored and is not to be used for this assignment (because it shows all ten nodes as if belonging to the same single Ethernet 192.168.1.0/24, rather than to an intranet composed of several Ethernets). Note that vm1 , . . . . . , vm10 are virtual machines, not real ones. One implication of this is that you will not be able to find out what their (virtual) IP addresses are by using nslookup and such. To find out these IP addresses, you need to look at the file /etc/hosts on minix. More to the point, invoking gethostbyname for a given vm will return to you only the (primary) IP address associated with the interface eth0 of that vm (which is the interface you will not be using). It will not return to you any other IP address for the node. Similarly, gethostbyaddr will return the vm node name only if you give it the (primary) IP address associated with the interface eth0 for the node. It will return nothing if you give it any other IP address for the node, even though the address is perfectly valid. Because of this, and because it will ease your task to be able to use gethostbyname and gethostbyaddr in a straightforward way, we shall adopt the (primary) IP addresses associated with interfaces eth0 as the ‘canonical’ IP addresses for the nodes (more on this below). Time client and server A time server runs on each of the ten vm machines. The client code should also be available on each vm so that it can be evoked at any of them. Normally, time clients/servers exchange request/reply messages using the TCP/UDP socket API that, effectively, enables them to receive service (indirectly, via the transport layer) from the local IP mechanism running at their nodes. You are to implement an API using Unix domain sockets to access the local ODR service directly (somewhat similar, in effect, to the way that raw sockets permit an application to access IP directly). Use Unix domain SOCK_DGRAM, rather than SOCK_STREAM, sockets (see Figures 15.5 & 15.6, pp. 418 - 419). API You need to implement a msg_send function that will be called by clients/servers to send requests/replies. The parameters of the function consist of : int giving the socket descriptor for write char* giving the ‘canonical’ IP address for the destination node, in presentation format int giving the destination ‘port’ number char* giving message to be sent int flag if set, force a route rediscovery to the destination node even if a non-‘stale’ route already exists (see below) msg_send will format these parameters into a single char sequence which is written to the Unix domain socket that a client/server process creates. The sequence will be read by the local ODR from a Unix domain socket that the ODR process creates for itself. Recall that the ‘canonical’ IP address for a vm node is the (primary) IP address associated with the eth0 interface for the node. It is what will be returned to you by a call to gethostbyname. Similarly, we need a msg_recv function which will do a (blocking) read on the application domain socket and return with : int giving socket descriptor for read char* giving message received char* giving ‘canonical’ IP address for the source node of message, in presentation format int* giving source ‘port’ number This information is written as a single char sequence by the ODR process to the domain socket that it creates for itself. It is read by msg_recv from the domain socket the client/server process creates, decomposed into the three components above, and returned to the caller of msg_recv. Also see the section below entitled ODR and the API. Client When a client is evoked at a node, it creates a domain datagram socket. The client should bind its socket to a ‘temporary’ (i.e., not ‘well-known’) sun_path name obtained from a call to tmpnam() (cf. line 10, Figure 15.6, p. 419) so that multiple clients may run at the same node. Note that tmpnam() is actually highly deprecated. You should use the mkstemp() function instead - look up the online man pages on minix (‘man mkstemp’) for details. As you run client code again and again during the development stage, the temporary files created by the calls to tmpnam / mkstemp start to proliferate since these files are not automatically removed when the client code terminates. You need to explicitly remove the file created by the client evocation by issuing a call to unlink() or to remove() in your client code just before the client code exits. See the online man pages on minix (‘man unlink’, ‘man remove’) for details. The client then enters an infinite loop repeating the steps below. The client prompts the user to choose one of vm1 , . . . . . , vm10 as a server node. Client msg_sends a 1 or 2 byte message to server and prints out on stdout the message client at node vm i1 sending request to server at vm i2 (In general, throughout this assignment, “trace” messages such as the one above should give the vm names and not IP addresses of the nodes.) Client then blocks in msg_recv awaiting response. This attempt to read from the domain socket should be backed up by a timeout in case no response ever comes. I leave it up to you whether you ‘wrap’ the call to msg_recv in a timeout, or you implement the timeout inside msg_recv itself. When the client receives a response it prints out on stdout the message client at node vm i1 : received from vm i2 <timestamp> If, on the other hand, the client times out, it should print out the message client at node vm i1 : timeout on response from vm i2 The client then retransmits the message out, setting the flag parameter in msg_send to force a route rediscovery, and prints out an appropriate message on stdout. This is done only once, when a timeout for a given message to the server occurs for the first time. Client repeats steps 1. - 3. Server The server creates a domain datagram socket. The server socket is assumed to have a (node-local) ‘well-known’ sun_path name which it binds to. This ‘well-known’ sun_path name is designated by a (network-wide) ‘well-known’ ‘port’ value. The time client uses this ‘port’ value to communicate with the server. The server enters an infinite sequence of calls to msg_recv followed by msg_send, awaiting client requests and responding to them. When it responds to a client request, it prints out on stdout the message server at node vm i1 responding to request from vm i2 ODR The ODR process runs on each of the ten vm machines. It is evoked with a single command line argument which gives a “staleness” time parameter, in seconds. It uses get_hw_addrs (available to you on minix in ~cse533/Asgn3_code) to obtain the index, and associated (unicast) IP and Ethernet addresses for each of the node’s interfaces, except for the eth0 and lo (loopback) interfaces, which should be ignored. In the subdirectory ~cse533/Asgn3_code (/users/cse533/Asgn3_code) on minix I am providing you with two functions, get_hw_addrs and prhwaddrs. These are analogous to the get_ifi_info_plus and prifinfo_plus of Assignment 2. Like get_ifi_info_plus, get_hw_addrs uses ioctl. get_hw_addrs gets the (primary) IP address, alias IP addresses (if any), HW address, and interface name and index value for each of the node's interfaces (including the loopback interface lo). prhwaddrs prints that information out. You should modify and use these functions as needed. Note that if an interface has no HW address associated with it (this is, typically, the case for the loopback interface lo for example), then ioctl returns get_hw_addrs a HW address which is the equivalent of 00:00:00:00:00:00 . get_hw_addrs stores this in the appropriate field of its data structures as it would with any HW address returned by ioctl, but when prhwaddrs comes across such an address, it prints a blank line instead of its usual ‘HWaddr = xx:xx:xx:xx:xx:xx’. The ODR process creates one or more PF_PACKET sockets. You will need to try out PF_PACKET sockets for yourselves and familiarize yourselves with how they behave. If, when you read from the socket and provide a sockaddr_ll structure, the kernel returns to you the index of the interface on which the incoming frame was received, then one socket will be enough. Otherwise, somewhat in the manner of Assignment 2, you shall have to create a PF_PACKET socket for every interface of interest (which are all the interfaces of the node, excluding interfaces lo and eth0 ), and bind a socket to each interface. Furthermore, if the kernel also returns to you the source Ethernet address of the frame in the sockaddr_ll structure, then you can make do with SOCK_DGRAM type PF_PACKET sockets; otherwise you shall have to use SOCK_RAW type sockets (although I would prefer you to use SOCK_RAW type sockets anyway, even if it turns out you can make do with SOCK_DGRAM type). The socket(s) should have a protocol value (no larger than 0xffff so that it fits in two bytes; this value is given as a network-byte-order parameter in the call(s) to function socket) that identifies your ODR protocol. The <linux/if_ether.h> include file (i.e., the file /usr/include/linux/if_ether.h) contains protocol values defined for the standard protocols typically found on an Ethernet LAN, as well as other values such as ETH_P_ALL. You should set protocol to a value of your choice which is not a <linux/if_ether.h> value, but which is, hopefully, unique to yourself. Remember that you will all be running your code using the same root account on the vm1 , . . . . . , vm10 nodes. So if two of you happen to choose the same protocol value and happen to be running on the same vm node at the same time, your applications will receive each other’s frames. For that reason, try to choose a protocol value for the socket(s) that is likely to be unique to yourself (something based on your Stony Brook student ID number, for example). This value effectively becomes the protocol value for your implementation of ODR, as opposed to some other cse 533 student's implementation. Because your value of protocol is to be carried in the frame type field of the Ethernet frame header, the value chosen should be not less than 1536 (0x600) so that it is not misinterpreted as the length of an Ethernet 802.3 frame. Note from the man pages for packet(7) that frames are passed to and from the socket without any processing in the frame content by the device driver on the other side of the socket, except for calculating and tagging on the 4-byte CRC trailer for outgoing frames, and stripping that trailer before delivering incoming frames to the socket. Nevertheless, if you write a frame that is less than 60 bytes, the necessary padding is automatically added by the device driver so that the frame that is actually transmitted out is the minimum Ethernet size of 64 bytes. When reading from the socket, however, any such padding that was introduced into a short frame at the sending node to bring it up to the minimum frame size is not stripped off - it is included in what you receive from the socket (thus, the minimum number of bytes you receive should never be less than 60). Also, you will have to build the frame header for outgoing frames yourselves (assuming you use SOCK_RAW type sockets). Bear in mind that the field values in that header have to be in network order. The ODR process also creates a domain datagram socket for communication with application processes at the node, and binds the socket to a ‘well known’ sun_path name for the ODR service. Because it is dealing with fixed topologies, ODR is, by and large, considerably simpler than AODV. In particular, discovered routes are relatively stable and there is no need for all the paraphernalia that goes with the possibility of routes changing (such as maintenance of active nodes in the routing tables and timeout mechanisms; timeouts on reverse links; lifetime field in the RREP messages; etc.) Nor will we be implementing source_sequence_#s (in the RREQ messages), and dest_sequence_# (in RREQ and RREP messages). In reality, we should (though we will not, for the sake of simplicity, be doing so) implement some sort of sequence number mechanism, or some alternative mechanism such as split-horizon for example, if we are to avoid possible scenarios of routing loops in a “count to infinity” context (I shall explain this point in class). However, we want ODR to discover shortest-hop paths, and we want it to do so in a reasonably efficient manner. This necessitates having one or two aspects of its operations work in a different, possibly slightly more complicated, way than AODV does. ODR has several basic responsibilities : Build and maintain a routing table. For each destination in the table, the routing table structure should include, at a minimum, the next-hop node (in the form of the Ethernet address for that node) and outgoing interface index, the number of hops to the destination, and a timestamp of when the the routing table entry was made or last “reconfirmed” / updated. Note that a destination node in the table is to be identified only by its ‘canonical’ IP address, and not by any other IP addresses the node has. Generate a RREQ in response to a time client calling msg_send for a destination for which ODR has no route (or for which a route exists, but msg_send has the flag parameter set or the route has gone ‘stale’ – see below), and ‘flood’ the RREQ out on all the node’s interfaces (except for the interface it came in on and, of course, the interfaces eth0 and lo). Flooding is done using an Ethernet broadcast destination address (0xff:ff:ff:ff:ff:ff) in the outgoing frame header. Note that a copy of the broadcast packet is supposed to / might be looped back to the node that sends it (see p. 535 in the Stevens textbook). ODR will have to take care not to treat these copies as new incoming RREQs. Also note that ODR at the client node increments the broadcast_id every time it issues a new RREQ for any destination node. When a RREQ is received, ODR has to generate a RREP if it is at the destination node, or if it is at an intermediate node that happens to have a route (which is not ‘stale’ – see below) to the destination. Otherwise, it must propagate the RREQ by flooding it out on all the node’s interfaces (except the interface the RREQ arrived on). Note that as it processes received RREQs, ODR should enter the ‘reverse’ route back to the source node into its routing table, or update an existing entry back to the source node if the RREQ received shows a shorter-hop route, or a route with the same number of hops but going through a different neighbour. The timestamp associated with the table entry should be updated whenever an existing route is either “reconfirmed” or updated. Obviously, if the node is going to generate a RREP, updating an existing entry back to the source node with a more efficient route, or a same-hops route using a different neighbour, should be done before the RREP is generated. Unlike AODV, when an intermediate node receives a RREQ for which it generates a RREP, it should nevertheless continue to flood the RREQ it received if the RREQ pertains to a source node whose existence it has heretofore been unaware of, or the RREQ gives it a more efficient route than it knew of back to the source node (the reason for continuing to flood the RREQ is so that other nodes in the intranet also become aware of the existence of the source node or of the potentially more optimal reverse route to it, and update their tables accordingly). However, since an RREP for this RREQ is being sent by our node, we do not want other nodes who receive the RREQ propagated by our node, and who might be in a position to do so, to also send RREPs. So we need to introduce a field in the RREQ message, not present in the AODV specifications, which acts like a “RREP already sent” field. Our node sets this field before further propagating the RREQ and nodes receiving an RREQ with this field set do not send RREPs in response, even if they are in a position to do so. ODR may, of course, receive multiple, distinct instances of the same RREQ (the combination of source_addr and broadcast_id uniquely identifies the RREQ). Such RREQs should not be flooded out unless they have a lower hop count than instances of that RREQ that had previously been received. By the same token, if ODR is in a position to send out a RREP, and has already done so for this, now repeating, RREQ , it should not send out another RREP unless the RREQ shows a more efficient, previously unknown, reverse route back to the source node. In other words, ODR should not generate essentially duplicative RREPs, nor generate RREPs to instances of RREQs that reflect reverse routes to the source that are not more efficient than what we already have. Relay RREPs received back to the source node (this is done using the ‘reverse’ route entered into the routing table when the corresponding RREQ was processed). At the same time, a ‘forward’ path to the destination is entered into the routing table. ODR could receive multiple, distinct RREPs for the same RREQ. The ‘forward’ route entered in the routing table should be updated to reflect the shortest-hop route to the destination, and RREPs reflecting suboptimal routes should not be relayed back to the source. In general, maintaining a route and its associated timestamp in the table in response to RREPs received is done in the same manner described above for RREQs. Forward time client/server messages along the next hop. (The following is important – you will lose points if you do not implement it.) Note that such application payload messages (especially if they are the initial request from the client to the server, rather than the server response back to the client) can be like “free” RREPs, enabling nodes along the path from source (client) to destination (server) node to build a reverse path back to the client node whose existence they were heretofore unaware of (or, possibly, to update an existing route with a more optimal one). Before it forwards an application payload message along the next hop, ODR at an intermediate node (and also at the final destination node) should use the message to update its routing table in this way. Thus, calls to msg_send by time servers should never cause ODR at the server node to initiate RREQs, since the receipt of a time client request implies that a route back to the client node should now exist in the routing table. The only exception to this is if the server node has a staleness parameter of zero (see below). A routing table entry has associated with it a timestamp that gives the time the entry was made into the table. When a client at a node calls msg_send, and if an entry for the destination node already exists in the routing table, ODR first checks that the routing information is not ‘stale’. A stale routing table entry is one that is older than the value defined by the staleness parameter given as a command line argument to the ODR process when it is executed. ODR deletes stale entries (as well as non-stale entries when the flag parameter in msg_send is set) and initiates a route rediscovery by issuing a RREQ for the destination node. This will force periodic updating of the routing tables to take care of failed nodes along the current path, Ethernet addresses that might have changed, and so on. Similarly, as RREQs propagate through the intranet, existing stale table entries at intermediate nodes are deleted and new route discoveries propagated. As noted above when discussing the processing of RREQs and RREPs, the associated timestamp for an existing table entry is updated in response to having the route either “reconfirmed” or updated (this applies to both reverse routes, by virtue of RREQs received, and to forward routes, by virtue of RREPs). Finally, note that a staleness parameter of 0 essentially indicates that the discovered route will be used only once, when first discovered, and then discarded. Effectively, an ODR with staleness parameter 0 maintains no real routing table at all ; instead, it forces route discoveries at every step of its operation. As a practical matter, ODR should be run with staleness parameter values that are considerably larger than the longest RTT on the intranet, otherwise performance will degrade considerably (and collapse entirely as the parameter values approach 0). Nevertheless, for robustness, we need to implement a mechanism by which an intermediate node that receives a RREP or application payload message for forwarding and finds that its relevant routing table entry has since gone stale, can intiate a RREQ to rediscover the route it needs. RREQ, RREP, and time client/server request/response messages will all have to be carried as encapsulated ODR protocol messages that form the data payload of Ethernet frames. So we need to design the structure of ODR protocol messages. The format should contain a type field (0 for RREQ, 1 for RREP, 2 for application payload ). The remaining fields in an ODR message will depend on what type it is. The fields needed for (our simplified versions of AODV’s) RREQ and RREP should be fairly clear to you, but keep in mind that you need to introduce two extra fields: The “RREP already sent” bit or field in RREQ messages, as mentioned above. A “forced discovery” bit or field in both RREQ and RREP messages: When a client application forces route rediscovery, this bit should be set in the RREQ issued by the client node ODR. Intermediate nodes that are not the destination node but which do have a route to the destination node should not respond with RREPs to an RREQ which has the forced discovery field set. Instead, they should continue to flood the RREQ so that it eventually reaches the destination node which will then respond with an RREP. The intermediate nodes relaying such an RREQ must update their ‘reverse’ route back to the source node accordingly, even if the new route is less efficient (i.e., has more hops) than the one they currently have in their routing table. The destination node responds to the RREQ with an RREP in which this field is also set. Intermediate nodes that receive such a forced discovery RREP must update their ‘forward’ route to the destination node accordingly, even if the new route is less efficient (i.e., has more hops) than the one they currently have in their routing table. This behaviour will cause a forced discovery RREQ to be responded to only by the destination node itself and not any other node, and will cause intermediate nodes to update their routing tables to both source and destination nodes in accordance with the latest routing information received, to cover the possibility that older routes are no longer valid because nodes and/or links along their paths have gone down. A type 2, application payload, message needs to contain the following type of information : type = 2 ‘canonical’ IP address of source node ‘port’ number of source application process (This, of course, is not a real port number in the TCP/UDP sense, but simply a value that ODR at the source node uses to designate the sun_path name for the source application’s domain socket.) ‘canonical’ IP address of destination node ‘port’ number of destination application process (This is passed to ODR by the application process at the source node when it calls msg_send. Its designates the sun_path name for an application’s domain socket at the destination node.) hop count (This starts at 0 and is incremented by 1 at each hop so that ODR can make use of the message to update its routing table, as discussed above.) number of bytes in application message The fields above essentially constitute a ‘header’ for the ODR message. Note that fields which you choose to have carry numeric values (rather than ascii characters, for example) must be in network byte order. ODR-defined numeric-valued fields in type 0, RREQ, and type 1, RREP, messages must, of course, also be in network byte order. Also note that only the ‘canonical’ IP addresses are used for the source and destination nodes in the ODR header. The same has to be true in the headers for type 0, RREQ, and type 1, RREP, messages. The general rule is that ODR messages only carry ‘canonical’ IP node addresses. The last field in the type 2 ODR message is essentially the data payload of the message. application message given in the call to msg_send An ODR protocol message is encapsulated as the data payload of an Ethernet frame whose header it fills in as follows : source address = Ethernet address of outgoing interface of the current node where ODR is processing the message. destination address = Ethernet broadcast address for type 0 messages; Ethernet address of next hop node for type 1 & 2 messages. protocol field = protocol value for the ODR PF_PACKET socket(s). Last but not least, whenever ODR writes an Ethernet frame out through its socket, it prints out on stdout the message ODR at node vm i1 : sending frame hdr src vm i1 dest addr ODR msg type n src vm i2 dest vm i3 where addr is in presentation format (i.e., hexadecimal xx:xx:xx:xx:xx:xx) and gives the destination Ethernet address in the outgoing frame header. Other nodes in the message should be identified by their vm name. A message should be printed out for each packet sent out on a distinct interface. ODR and the API When the ODR process first starts, it must construct a table in which it enters all well-known ‘port’ numbers and their corresponding sun_path names. These will constitute permanent entries in the table. Thereafter, whenever it reads a message off its domain socket, it must obtain the sun_path name for the peer process socket and check whether that name is entered in the table. If not, it must select an ‘ephemeral’ ‘port’ value by which to designate the peer sun_path name and enter the pair < port value , sun_path name > into the table. Such entries cannot be permanent otherwise the table will grow unboundedly in time, with entries surviving for ever, beyond the peer processes’ demise. We must associate a time_to_live field with a non-permanent table entry, and purge the entry if nothing is heard from the peer for that amount of time. Every time a peer process for which a non-permanent table entry exists communicates with ODR, its time_to_live value should be reinitialized. Note that when ODR writes to a peer, it is possible for the write to fail because the peer does not exist : it could be a ‘well-known’ service that is not running, or we could be in the interval between a process with a non-permanent table entry terminating and the expiration of its time_to_live value. Notes A proper implementation of ODR would probably require that RREQ and RREP messages be backed up by some kind of timeout and retransmission mechanism since the network transmission environment is not reliable. This would considerably complicate the implementation (because at any given moment, a node could have multiple RREQs that it has flooded out, but for which it has still not received RREPs; the situation is further complicated by the fact that not all intermediate nodes receiving and relaying RREQs necessarily lie on a path to the destination, and therefore should expect to receive RREPs), and, learning-wise, would not add much to the experience you should have gained from Assignment 2.
Aryia-Behroziuan / NumpyQuickstart tutorial Prerequisites Before reading this tutorial you should know a bit of Python. If you would like to refresh your memory, take a look at the Python tutorial. If you wish to work the examples in this tutorial, you must also have some software installed on your computer. Please see https://scipy.org/install.html for instructions. Learner profile This tutorial is intended as a quick overview of algebra and arrays in NumPy and want to understand how n-dimensional (n>=2) arrays are represented and can be manipulated. In particular, if you don’t know how to apply common functions to n-dimensional arrays (without using for-loops), or if you want to understand axis and shape properties for n-dimensional arrays, this tutorial might be of help. Learning Objectives After this tutorial, you should be able to: Understand the difference between one-, two- and n-dimensional arrays in NumPy; Understand how to apply some linear algebra operations to n-dimensional arrays without using for-loops; Understand axis and shape properties for n-dimensional arrays. The Basics NumPy’s main object is the homogeneous multidimensional array. It is a table of elements (usually numbers), all of the same type, indexed by a tuple of non-negative integers. In NumPy dimensions are called axes. For example, the coordinates of a point in 3D space [1, 2, 1] has one axis. That axis has 3 elements in it, so we say it has a length of 3. In the example pictured below, the array has 2 axes. The first axis has a length of 2, the second axis has a length of 3. [[ 1., 0., 0.], [ 0., 1., 2.]] NumPy’s array class is called ndarray. It is also known by the alias array. Note that numpy.array is not the same as the Standard Python Library class array.array, which only handles one-dimensional arrays and offers less functionality. The more important attributes of an ndarray object are: ndarray.ndim the number of axes (dimensions) of the array. ndarray.shape the dimensions of the array. This is a tuple of integers indicating the size of the array in each dimension. For a matrix with n rows and m columns, shape will be (n,m). The length of the shape tuple is therefore the number of axes, ndim. ndarray.size the total number of elements of the array. This is equal to the product of the elements of shape. ndarray.dtype an object describing the type of the elements in the array. One can create or specify dtype’s using standard Python types. Additionally NumPy provides types of its own. numpy.int32, numpy.int16, and numpy.float64 are some examples. ndarray.itemsize the size in bytes of each element of the array. For example, an array of elements of type float64 has itemsize 8 (=64/8), while one of type complex32 has itemsize 4 (=32/8). It is equivalent to ndarray.dtype.itemsize. ndarray.data the buffer containing the actual elements of the array. Normally, we won’t need to use this attribute because we will access the elements in an array using indexing facilities. An example >>> import numpy as np a = np.arange(15).reshape(3, 5) a array([[ 0, 1, 2, 3, 4], [ 5, 6, 7, 8, 9], [10, 11, 12, 13, 14]]) a.shape (3, 5) a.ndim 2 a.dtype.name 'int64' a.itemsize 8 a.size 15 type(a) <class 'numpy.ndarray'> b = np.array([6, 7, 8]) b array([6, 7, 8]) type(b) <class 'numpy.ndarray'> Array Creation There are several ways to create arrays. For example, you can create an array from a regular Python list or tuple using the array function. The type of the resulting array is deduced from the type of the elements in the sequences. >>> >>> import numpy as np >>> a = np.array([2,3,4]) >>> a array([2, 3, 4]) >>> a.dtype dtype('int64') >>> b = np.array([1.2, 3.5, 5.1]) >>> b.dtype dtype('float64') A frequent error consists in calling array with multiple arguments, rather than providing a single sequence as an argument. >>> >>> a = np.array(1,2,3,4) # WRONG Traceback (most recent call last): ... TypeError: array() takes from 1 to 2 positional arguments but 4 were given >>> a = np.array([1,2,3,4]) # RIGHT array transforms sequences of sequences into two-dimensional arrays, sequences of sequences of sequences into three-dimensional arrays, and so on. >>> >>> b = np.array([(1.5,2,3), (4,5,6)]) >>> b array([[1.5, 2. , 3. ], [4. , 5. , 6. ]]) The type of the array can also be explicitly specified at creation time: >>> >>> c = np.array( [ [1,2], [3,4] ], dtype=complex ) >>> c array([[1.+0.j, 2.+0.j], [3.+0.j, 4.+0.j]]) Often, the elements of an array are originally unknown, but its size is known. Hence, NumPy offers several functions to create arrays with initial placeholder content. These minimize the necessity of growing arrays, an expensive operation. The function zeros creates an array full of zeros, the function ones creates an array full of ones, and the function empty creates an array whose initial content is random and depends on the state of the memory. By default, the dtype of the created array is float64. >>> >>> np.zeros((3, 4)) array([[0., 0., 0., 0.], [0., 0., 0., 0.], [0., 0., 0., 0.]]) >>> np.ones( (2,3,4), dtype=np.int16 ) # dtype can also be specified array([[[1, 1, 1, 1], [1, 1, 1, 1], [1, 1, 1, 1]], [[1, 1, 1, 1], [1, 1, 1, 1], [1, 1, 1, 1]]], dtype=int16) >>> np.empty( (2,3) ) # uninitialized array([[ 3.73603959e-262, 6.02658058e-154, 6.55490914e-260], # may vary [ 5.30498948e-313, 3.14673309e-307, 1.00000000e+000]]) To create sequences of numbers, NumPy provides the arange function which is analogous to the Python built-in range, but returns an array. >>> >>> np.arange( 10, 30, 5 ) array([10, 15, 20, 25]) >>> np.arange( 0, 2, 0.3 ) # it accepts float arguments array([0. , 0.3, 0.6, 0.9, 1.2, 1.5, 1.8]) When arange is used with floating point arguments, it is generally not possible to predict the number of elements obtained, due to the finite floating point precision. For this reason, it is usually better to use the function linspace that receives as an argument the number of elements that we want, instead of the step: >>> >>> from numpy import pi >>> np.linspace( 0, 2, 9 ) # 9 numbers from 0 to 2 array([0. , 0.25, 0.5 , 0.75, 1. , 1.25, 1.5 , 1.75, 2. ]) >>> x = np.linspace( 0, 2*pi, 100 ) # useful to evaluate function at lots of points >>> f = np.sin(x) See also array, zeros, zeros_like, ones, ones_like, empty, empty_like, arange, linspace, numpy.random.Generator.rand, numpy.random.Generator.randn, fromfunction, fromfile Printing Arrays When you print an array, NumPy displays it in a similar way to nested lists, but with the following layout: the last axis is printed from left to right, the second-to-last is printed from top to bottom, the rest are also printed from top to bottom, with each slice separated from the next by an empty line. One-dimensional arrays are then printed as rows, bidimensionals as matrices and tridimensionals as lists of matrices. >>> >>> a = np.arange(6) # 1d array >>> print(a) [0 1 2 3 4 5] >>> >>> b = np.arange(12).reshape(4,3) # 2d array >>> print(b) [[ 0 1 2] [ 3 4 5] [ 6 7 8] [ 9 10 11]] >>> >>> c = np.arange(24).reshape(2,3,4) # 3d array >>> print(c) [[[ 0 1 2 3] [ 4 5 6 7] [ 8 9 10 11]] [[12 13 14 15] [16 17 18 19] [20 21 22 23]]] See below to get more details on reshape. If an array is too large to be printed, NumPy automatically skips the central part of the array and only prints the corners: >>> >>> print(np.arange(10000)) [ 0 1 2 ... 9997 9998 9999] >>> >>> print(np.arange(10000).reshape(100,100)) [[ 0 1 2 ... 97 98 99] [ 100 101 102 ... 197 198 199] [ 200 201 202 ... 297 298 299] ... [9700 9701 9702 ... 9797 9798 9799] [9800 9801 9802 ... 9897 9898 9899] [9900 9901 9902 ... 9997 9998 9999]] To disable this behaviour and force NumPy to print the entire array, you can change the printing options using set_printoptions. >>> >>> np.set_printoptions(threshold=sys.maxsize) # sys module should be imported Basic Operations Arithmetic operators on arrays apply elementwise. A new array is created and filled with the result. >>> >>> a = np.array( [20,30,40,50] ) >>> b = np.arange( 4 ) >>> b array([0, 1, 2, 3]) >>> c = a-b >>> c array([20, 29, 38, 47]) >>> b**2 array([0, 1, 4, 9]) >>> 10*np.sin(a) array([ 9.12945251, -9.88031624, 7.4511316 , -2.62374854]) >>> a<35 array([ True, True, False, False]) Unlike in many matrix languages, the product operator * operates elementwise in NumPy arrays. The matrix product can be performed using the @ operator (in python >=3.5) or the dot function or method: >>> >>> A = np.array( [[1,1], ... [0,1]] ) >>> B = np.array( [[2,0], ... [3,4]] ) >>> A * B # elementwise product array([[2, 0], [0, 4]]) >>> A @ B # matrix product array([[5, 4], [3, 4]]) >>> A.dot(B) # another matrix product array([[5, 4], [3, 4]]) Some operations, such as += and *=, act in place to modify an existing array rather than create a new one. >>> >>> rg = np.random.default_rng(1) # create instance of default random number generator >>> a = np.ones((2,3), dtype=int) >>> b = rg.random((2,3)) >>> a *= 3 >>> a array([[3, 3, 3], [3, 3, 3]]) >>> b += a >>> b array([[3.51182162, 3.9504637 , 3.14415961], [3.94864945, 3.31183145, 3.42332645]]) >>> a += b # b is not automatically converted to integer type Traceback (most recent call last): ... numpy.core._exceptions.UFuncTypeError: Cannot cast ufunc 'add' output from dtype('float64') to dtype('int64') with casting rule 'same_kind' When operating with arrays of different types, the type of the resulting array corresponds to the more general or precise one (a behavior known as upcasting). >>> >>> a = np.ones(3, dtype=np.int32) >>> b = np.linspace(0,pi,3) >>> b.dtype.name 'float64' >>> c = a+b >>> c array([1. , 2.57079633, 4.14159265]) >>> c.dtype.name 'float64' >>> d = np.exp(c*1j) >>> d array([ 0.54030231+0.84147098j, -0.84147098+0.54030231j, -0.54030231-0.84147098j]) >>> d.dtype.name 'complex128' Many unary operations, such as computing the sum of all the elements in the array, are implemented as methods of the ndarray class. >>> >>> a = rg.random((2,3)) >>> a array([[0.82770259, 0.40919914, 0.54959369], [0.02755911, 0.75351311, 0.53814331]]) >>> a.sum() 3.1057109529998157 >>> a.min() 0.027559113243068367 >>> a.max() 0.8277025938204418 By default, these operations apply to the array as though it were a list of numbers, regardless of its shape. However, by specifying the axis parameter you can apply an operation along the specified axis of an array: >>> >>> b = np.arange(12).reshape(3,4) >>> b array([[ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11]]) >>> >>> b.sum(axis=0) # sum of each column array([12, 15, 18, 21]) >>> >>> b.min(axis=1) # min of each row array([0, 4, 8]) >>> >>> b.cumsum(axis=1) # cumulative sum along each row array([[ 0, 1, 3, 6], [ 4, 9, 15, 22], [ 8, 17, 27, 38]]) Universal Functions NumPy provides familiar mathematical functions such as sin, cos, and exp. In NumPy, these are called “universal functions”(ufunc). Within NumPy, these functions operate elementwise on an array, producing an array as output. >>> >>> B = np.arange(3) >>> B array([0, 1, 2]) >>> np.exp(B) array([1. , 2.71828183, 7.3890561 ]) >>> np.sqrt(B) array([0. , 1. , 1.41421356]) >>> C = np.array([2., -1., 4.]) >>> np.add(B, C) array([2., 0., 6.]) See also all, any, apply_along_axis, argmax, argmin, argsort, average, bincount, ceil, clip, conj, corrcoef, cov, cross, cumprod, cumsum, diff, dot, floor, inner, invert, lexsort, max, maximum, mean, median, min, minimum, nonzero, outer, prod, re, round, sort, std, sum, trace, transpose, var, vdot, vectorize, where Indexing, Slicing and Iterating One-dimensional arrays can be indexed, sliced and iterated over, much like lists and other Python sequences. >>> >>> a = np.arange(10)**3 >>> a array([ 0, 1, 8, 27, 64, 125, 216, 343, 512, 729]) >>> a[2] 8 >>> a[2:5] array([ 8, 27, 64]) # equivalent to a[0:6:2] = 1000; # from start to position 6, exclusive, set every 2nd element to 1000 >>> a[:6:2] = 1000 >>> a array([1000, 1, 1000, 27, 1000, 125, 216, 343, 512, 729]) >>> a[ : :-1] # reversed a array([ 729, 512, 343, 216, 125, 1000, 27, 1000, 1, 1000]) >>> for i in a: ... print(i**(1/3.)) ... 9.999999999999998 1.0 9.999999999999998 3.0 9.999999999999998 4.999999999999999 5.999999999999999 6.999999999999999 7.999999999999999 8.999999999999998 Multidimensional arrays can have one index per axis. These indices are given in a tuple separated by commas: >>> >>> def f(x,y): ... return 10*x+y ... >>> b = np.fromfunction(f,(5,4),dtype=int) >>> b array([[ 0, 1, 2, 3], [10, 11, 12, 13], [20, 21, 22, 23], [30, 31, 32, 33], [40, 41, 42, 43]]) >>> b[2,3] 23 >>> b[0:5, 1] # each row in the second column of b array([ 1, 11, 21, 31, 41]) >>> b[ : ,1] # equivalent to the previous example array([ 1, 11, 21, 31, 41]) >>> b[1:3, : ] # each column in the second and third row of b array([[10, 11, 12, 13], [20, 21, 22, 23]]) When fewer indices are provided than the number of axes, the missing indices are considered complete slices: >>> >>> b[-1] # the last row. Equivalent to b[-1,:] array([40, 41, 42, 43]) The expression within brackets in b[i] is treated as an i followed by as many instances of : as needed to represent the remaining axes. NumPy also allows you to write this using dots as b[i,...]. The dots (...) represent as many colons as needed to produce a complete indexing tuple. For example, if x is an array with 5 axes, then x[1,2,...] is equivalent to x[1,2,:,:,:], x[...,3] to x[:,:,:,:,3] and x[4,...,5,:] to x[4,:,:,5,:]. >>> >>> c = np.array( [[[ 0, 1, 2], # a 3D array (two stacked 2D arrays) ... [ 10, 12, 13]], ... [[100,101,102], ... [110,112,113]]]) >>> c.shape (2, 2, 3) >>> c[1,...] # same as c[1,:,:] or c[1] array([[100, 101, 102], [110, 112, 113]]) >>> c[...,2] # same as c[:,:,2] array([[ 2, 13], [102, 113]]) Iterating over multidimensional arrays is done with respect to the first axis: >>> >>> for row in b: ... print(row) ... [0 1 2 3] [10 11 12 13] [20 21 22 23] [30 31 32 33] [40 41 42 43] However, if one wants to perform an operation on each element in the array, one can use the flat attribute which is an iterator over all the elements of the array: >>> >>> for element in b.flat: ... print(element) ... 0 1 2 3 10 11 12 13 20 21 22 23 30 31 32 33 40 41 42 43 See also Indexing, Indexing (reference), newaxis, ndenumerate, indices Shape Manipulation Changing the shape of an array An array has a shape given by the number of elements along each axis: >>> >>> a = np.floor(10*rg.random((3,4))) >>> a array([[3., 7., 3., 4.], [1., 4., 2., 2.], [7., 2., 4., 9.]]) >>> a.shape (3, 4) The shape of an array can be changed with various commands. Note that the following three commands all return a modified array, but do not change the original array: >>> >>> a.ravel() # returns the array, flattened array([3., 7., 3., 4., 1., 4., 2., 2., 7., 2., 4., 9.]) >>> a.reshape(6,2) # returns the array with a modified shape array([[3., 7.], [3., 4.], [1., 4.], [2., 2.], [7., 2.], [4., 9.]]) >>> a.T # returns the array, transposed array([[3., 1., 7.], [7., 4., 2.], [3., 2., 4.], [4., 2., 9.]]) >>> a.T.shape (4, 3) >>> a.shape (3, 4) The order of the elements in the array resulting from ravel() is normally “C-style”, that is, the rightmost index “changes the fastest”, so the element after a[0,0] is a[0,1]. If the array is reshaped to some other shape, again the array is treated as “C-style”. NumPy normally creates arrays stored in this order, so ravel() will usually not need to copy its argument, but if the array was made by taking slices of another array or created with unusual options, it may need to be copied. The functions ravel() and reshape() can also be instructed, using an optional argument, to use FORTRAN-style arrays, in which the leftmost index changes the fastest. The reshape function returns its argument with a modified shape, whereas the ndarray.resize method modifies the array itself: >>> >>> a array([[3., 7., 3., 4.], [1., 4., 2., 2.], [7., 2., 4., 9.]]) >>> a.resize((2,6)) >>> a array([[3., 7., 3., 4., 1., 4.], [2., 2., 7., 2., 4., 9.]]) If a dimension is given as -1 in a reshaping operation, the other dimensions are automatically calculated: >>> >>> a.reshape(3,-1) array([[3., 7., 3., 4.], [1., 4., 2., 2.], [7., 2., 4., 9.]]) See also ndarray.shape, reshape, resize, ravel Stacking together different arrays Several arrays can be stacked together along different axes: >>> >>> a = np.floor(10*rg.random((2,2))) >>> a array([[9., 7.], [5., 2.]]) >>> b = np.floor(10*rg.random((2,2))) >>> b array([[1., 9.], [5., 1.]]) >>> np.vstack((a,b)) array([[9., 7.], [5., 2.], [1., 9.], [5., 1.]]) >>> np.hstack((a,b)) array([[9., 7., 1., 9.], [5., 2., 5., 1.]]) The function column_stack stacks 1D arrays as columns into a 2D array. It is equivalent to hstack only for 2D arrays: >>> >>> from numpy import newaxis >>> np.column_stack((a,b)) # with 2D arrays array([[9., 7., 1., 9.], [5., 2., 5., 1.]]) >>> a = np.array([4.,2.]) >>> b = np.array([3.,8.]) >>> np.column_stack((a,b)) # returns a 2D array array([[4., 3.], [2., 8.]]) >>> np.hstack((a,b)) # the result is different array([4., 2., 3., 8.]) >>> a[:,newaxis] # view `a` as a 2D column vector array([[4.], [2.]]) >>> np.column_stack((a[:,newaxis],b[:,newaxis])) array([[4., 3.], [2., 8.]]) >>> np.hstack((a[:,newaxis],b[:,newaxis])) # the result is the same array([[4., 3.], [2., 8.]]) On the other hand, the function row_stack is equivalent to vstack for any input arrays. In fact, row_stack is an alias for vstack: >>> >>> np.column_stack is np.hstack False >>> np.row_stack is np.vstack True In general, for arrays with more than two dimensions, hstack stacks along their second axes, vstack stacks along their first axes, and concatenate allows for an optional arguments giving the number of the axis along which the concatenation should happen. Note In complex cases, r_ and c_ are useful for creating arrays by stacking numbers along one axis. They allow the use of range literals (“:”) >>> >>> np.r_[1:4,0,4] array([1, 2, 3, 0, 4]) When used with arrays as arguments, r_ and c_ are similar to vstack and hstack in their default behavior, but allow for an optional argument giving the number of the axis along which to concatenate. See also hstack, vstack, column_stack, concatenate, c_, r_ Splitting one array into several smaller ones Using hsplit, you can split an array along its horizontal axis, either by specifying the number of equally shaped arrays to return, or by specifying the columns after which the division should occur: >>> >>> a = np.floor(10*rg.random((2,12))) >>> a array([[6., 7., 6., 9., 0., 5., 4., 0., 6., 8., 5., 2.], [8., 5., 5., 7., 1., 8., 6., 7., 1., 8., 1., 0.]]) # Split a into 3 >>> np.hsplit(a,3) [array([[6., 7., 6., 9.], [8., 5., 5., 7.]]), array([[0., 5., 4., 0.], [1., 8., 6., 7.]]), array([[6., 8., 5., 2.], [1., 8., 1., 0.]])] # Split a after the third and the fourth column >>> np.hsplit(a,(3,4)) [array([[6., 7., 6.], [8., 5., 5.]]), array([[9.], [7.]]), array([[0., 5., 4., 0., 6., 8., 5., 2.], [1., 8., 6., 7., 1., 8., 1., 0.]])] vsplit splits along the vertical axis, and array_split allows one to specify along which axis to split. Copies and Views When operating and manipulating arrays, their data is sometimes copied into a new array and sometimes not. This is often a source of confusion for beginners. There are three cases: No Copy at All Simple assignments make no copy of objects or their data. >>> >>> a = np.array([[ 0, 1, 2, 3], ... [ 4, 5, 6, 7], ... [ 8, 9, 10, 11]]) >>> b = a # no new object is created >>> b is a # a and b are two names for the same ndarray object True Python passes mutable objects as references, so function calls make no copy. >>> >>> def f(x): ... print(id(x)) ... >>> id(a) # id is a unique identifier of an object 148293216 # may vary >>> f(a) 148293216 # may vary View or Shallow Copy Different array objects can share the same data. The view method creates a new array object that looks at the same data. >>> >>> c = a.view() >>> c is a False >>> c.base is a # c is a view of the data owned by a True >>> c.flags.owndata False >>> >>> c = c.reshape((2, 6)) # a's shape doesn't change >>> a.shape (3, 4) >>> c[0, 4] = 1234 # a's data changes >>> a array([[ 0, 1, 2, 3], [1234, 5, 6, 7], [ 8, 9, 10, 11]]) Slicing an array returns a view of it: >>> >>> s = a[ : , 1:3] # spaces added for clarity; could also be written "s = a[:, 1:3]" >>> s[:] = 10 # s[:] is a view of s. Note the difference between s = 10 and s[:] = 10 >>> a array([[ 0, 10, 10, 3], [1234, 10, 10, 7], [ 8, 10, 10, 11]]) Deep Copy The copy method makes a complete copy of the array and its data. >>> >>> d = a.copy() # a new array object with new data is created >>> d is a False >>> d.base is a # d doesn't share anything with a False >>> d[0,0] = 9999 >>> a array([[ 0, 10, 10, 3], [1234, 10, 10, 7], [ 8, 10, 10, 11]]) Sometimes copy should be called after slicing if the original array is not required anymore. For example, suppose a is a huge intermediate result and the final result b only contains a small fraction of a, a deep copy should be made when constructing b with slicing: >>> >>> a = np.arange(int(1e8)) >>> b = a[:100].copy() >>> del a # the memory of ``a`` can be released. If b = a[:100] is used instead, a is referenced by b and will persist in memory even if del a is executed. Functions and Methods Overview Here is a list of some useful NumPy functions and methods names ordered in categories. See Routines for the full list. Array Creation arange, array, copy, empty, empty_like, eye, fromfile, fromfunction, identity, linspace, logspace, mgrid, ogrid, ones, ones_like, r_, zeros, zeros_like Conversions ndarray.astype, atleast_1d, atleast_2d, atleast_3d, mat Manipulations array_split, column_stack, concatenate, diagonal, dsplit, dstack, hsplit, hstack, ndarray.item, newaxis, ravel, repeat, reshape, resize, squeeze, swapaxes, take, transpose, vsplit, vstack Questions all, any, nonzero, where Ordering argmax, argmin, argsort, max, min, ptp, searchsorted, sort Operations choose, compress, cumprod, cumsum, inner, ndarray.fill, imag, prod, put, putmask, real, sum Basic Statistics cov, mean, std, var Basic Linear Algebra cross, dot, outer, linalg.svd, vdot Less Basic Broadcasting rules Broadcasting allows universal functions to deal in a meaningful way with inputs that do not have exactly the same shape. The first rule of broadcasting is that if all input arrays do not have the same number of dimensions, a “1” will be repeatedly prepended to the shapes of the smaller arrays until all the arrays have the same number of dimensions. The second rule of broadcasting ensures that arrays with a size of 1 along a particular dimension act as if they had the size of the array with the largest shape along that dimension. The value of the array element is assumed to be the same along that dimension for the “broadcast” array. After application of the broadcasting rules, the sizes of all arrays must match. More details can be found in Broadcasting. Advanced indexing and index tricks NumPy offers more indexing facilities than regular Python sequences. In addition to indexing by integers and slices, as we saw before, arrays can be indexed by arrays of integers and arrays of booleans. Indexing with Arrays of Indices >>> >>> a = np.arange(12)**2 # the first 12 square numbers >>> i = np.array([1, 1, 3, 8, 5]) # an array of indices >>> a[i] # the elements of a at the positions i array([ 1, 1, 9, 64, 25]) >>> >>> j = np.array([[3, 4], [9, 7]]) # a bidimensional array of indices >>> a[j] # the same shape as j array([[ 9, 16], [81, 49]]) When the indexed array a is multidimensional, a single array of indices refers to the first dimension of a. The following example shows this behavior by converting an image of labels into a color image using a palette. >>> >>> palette = np.array([[0, 0, 0], # black ... [255, 0, 0], # red ... [0, 255, 0], # green ... [0, 0, 255], # blue ... [255, 255, 255]]) # white >>> image = np.array([[0, 1, 2, 0], # each value corresponds to a color in the palette ... [0, 3, 4, 0]]) >>> palette[image] # the (2, 4, 3) color image array([[[ 0, 0, 0], [255, 0, 0], [ 0, 255, 0], [ 0, 0, 0]], [[ 0, 0, 0], [ 0, 0, 255], [255, 255, 255], [ 0, 0, 0]]]) We can also give indexes for more than one dimension. The arrays of indices for each dimension must have the same shape. >>> >>> a = np.arange(12).reshape(3,4) >>> a array([[ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11]]) >>> i = np.array([[0, 1], # indices for the first dim of a ... [1, 2]]) >>> j = np.array([[2, 1], # indices for the second dim ... [3, 3]]) >>> >>> a[i, j] # i and j must have equal shape array([[ 2, 5], [ 7, 11]]) >>> >>> a[i, 2] array([[ 2, 6], [ 6, 10]]) >>> >>> a[:, j] # i.e., a[ : , j] array([[[ 2, 1], [ 3, 3]], [[ 6, 5], [ 7, 7]], [[10, 9], [11, 11]]]) In Python, arr[i, j] is exactly the same as arr[(i, j)]—so we can put i and j in a tuple and then do the indexing with that. >>> >>> l = (i, j) # equivalent to a[i, j] >>> a[l] array([[ 2, 5], [ 7, 11]]) However, we can not do this by putting i and j into an array, because this array will be interpreted as indexing the first dimension of a. >>> >>> s = np.array([i, j]) # not what we want >>> a[s] Traceback (most recent call last): File "<stdin>", line 1, in <module> IndexError: index 3 is out of bounds for axis 0 with size 3 # same as a[i, j] >>> a[tuple(s)] array([[ 2, 5], [ 7, 11]]) Another common use of indexing with arrays is the search of the maximum value of time-dependent series: >>> >>> time = np.linspace(20, 145, 5) # time scale >>> data = np.sin(np.arange(20)).reshape(5,4) # 4 time-dependent series >>> time array([ 20. , 51.25, 82.5 , 113.75, 145. ]) >>> data array([[ 0. , 0.84147098, 0.90929743, 0.14112001], [-0.7568025 , -0.95892427, -0.2794155 , 0.6569866 ], [ 0.98935825, 0.41211849, -0.54402111, -0.99999021], [-0.53657292, 0.42016704, 0.99060736, 0.65028784], [-0.28790332, -0.96139749, -0.75098725, 0.14987721]]) # index of the maxima for each series >>> ind = data.argmax(axis=0) >>> ind array([2, 0, 3, 1]) # times corresponding to the maxima >>> time_max = time[ind] >>> >>> data_max = data[ind, range(data.shape[1])] # => data[ind[0],0], data[ind[1],1]... >>> time_max array([ 82.5 , 20. , 113.75, 51.25]) >>> data_max array([0.98935825, 0.84147098, 0.99060736, 0.6569866 ]) >>> np.all(data_max == data.max(axis=0)) True You can also use indexing with arrays as a target to assign to: >>> >>> a = np.arange(5) >>> a array([0, 1, 2, 3, 4]) >>> a[[1,3,4]] = 0 >>> a array([0, 0, 2, 0, 0]) However, when the list of indices contains repetitions, the assignment is done several times, leaving behind the last value: >>> >>> a = np.arange(5) >>> a[[0,0,2]]=[1,2,3] >>> a array([2, 1, 3, 3, 4]) This is reasonable enough, but watch out if you want to use Python’s += construct, as it may not do what you expect: >>> >>> a = np.arange(5) >>> a[[0,0,2]]+=1 >>> a array([1, 1, 3, 3, 4]) Even though 0 occurs twice in the list of indices, the 0th element is only incremented once. This is because Python requires “a+=1” to be equivalent to “a = a + 1”. Indexing with Boolean Arrays When we index arrays with arrays of (integer) indices we are providing the list of indices to pick. With boolean indices the approach is different; we explicitly choose which items in the array we want and which ones we don’t. The most natural way one can think of for boolean indexing is to use boolean arrays that have the same shape as the original array: >>> >>> a = np.arange(12).reshape(3,4) >>> b = a > 4 >>> b # b is a boolean with a's shape array([[False, False, False, False], [False, True, True, True], [ True, True, True, True]]) >>> a[b] # 1d array with the selected elements array([ 5, 6, 7, 8, 9, 10, 11]) This property can be very useful in assignments: >>> >>> a[b] = 0 # All elements of 'a' higher than 4 become 0 >>> a array([[0, 1, 2, 3], [4, 0, 0, 0], [0, 0, 0, 0]]) You can look at the following example to see how to use boolean indexing to generate an image of the Mandelbrot set: >>> import numpy as np import matplotlib.pyplot as plt def mandelbrot( h,w, maxit=20 ): """Returns an image of the Mandelbrot fractal of size (h,w).""" y,x = np.ogrid[ -1.4:1.4:h*1j, -2:0.8:w*1j ] c = x+y*1j z = c divtime = maxit + np.zeros(z.shape, dtype=int) for i in range(maxit): z = z**2 + c diverge = z*np.conj(z) > 2**2 # who is diverging div_now = diverge & (divtime==maxit) # who is diverging now divtime[div_now] = i # note when z[diverge] = 2 # avoid diverging too much return divtime plt.imshow(mandelbrot(400,400)) ../_images/quickstart-1.png The second way of indexing with booleans is more similar to integer indexing; for each dimension of the array we give a 1D boolean array selecting the slices we want: >>> >>> a = np.arange(12).reshape(3,4) >>> b1 = np.array([False,True,True]) # first dim selection >>> b2 = np.array([True,False,True,False]) # second dim selection >>> >>> a[b1,:] # selecting rows array([[ 4, 5, 6, 7], [ 8, 9, 10, 11]]) >>> >>> a[b1] # same thing array([[ 4, 5, 6, 7], [ 8, 9, 10, 11]]) >>> >>> a[:,b2] # selecting columns array([[ 0, 2], [ 4, 6], [ 8, 10]]) >>> >>> a[b1,b2] # a weird thing to do array([ 4, 10]) Note that the length of the 1D boolean array must coincide with the length of the dimension (or axis) you want to slice. In the previous example, b1 has length 3 (the number of rows in a), and b2 (of length 4) is suitable to index the 2nd axis (columns) of a. The ix_() function The ix_ function can be used to combine different vectors so as to obtain the result for each n-uplet. For example, if you want to compute all the a+b*c for all the triplets taken from each of the vectors a, b and c: >>> >>> a = np.array([2,3,4,5]) >>> b = np.array([8,5,4]) >>> c = np.array([5,4,6,8,3]) >>> ax,bx,cx = np.ix_(a,b,c) >>> ax array([[[2]], [[3]], [[4]], [[5]]]) >>> bx array([[[8], [5], [4]]]) >>> cx array([[[5, 4, 6, 8, 3]]]) >>> ax.shape, bx.shape, cx.shape ((4, 1, 1), (1, 3, 1), (1, 1, 5)) >>> result = ax+bx*cx >>> result array([[[42, 34, 50, 66, 26], [27, 22, 32, 42, 17], [22, 18, 26, 34, 14]], [[43, 35, 51, 67, 27], [28, 23, 33, 43, 18], [23, 19, 27, 35, 15]], [[44, 36, 52, 68, 28], [29, 24, 34, 44, 19], [24, 20, 28, 36, 16]], [[45, 37, 53, 69, 29], [30, 25, 35, 45, 20], [25, 21, 29, 37, 17]]]) >>> result[3,2,4] 17 >>> a[3]+b[2]*c[4] 17 You could also implement the reduce as follows: >>> >>> def ufunc_reduce(ufct, *vectors): ... vs = np.ix_(*vectors) ... r = ufct.identity ... for v in vs: ... r = ufct(r,v) ... return r and then use it as: >>> >>> ufunc_reduce(np.add,a,b,c) array([[[15, 14, 16, 18, 13], [12, 11, 13, 15, 10], [11, 10, 12, 14, 9]], [[16, 15, 17, 19, 14], [13, 12, 14, 16, 11], [12, 11, 13, 15, 10]], [[17, 16, 18, 20, 15], [14, 13, 15, 17, 12], [13, 12, 14, 16, 11]], [[18, 17, 19, 21, 16], [15, 14, 16, 18, 13], [14, 13, 15, 17, 12]]]) The advantage of this version of reduce compared to the normal ufunc.reduce is that it makes use of the Broadcasting Rules in order to avoid creating an argument array the size of the output times the number of vectors. Indexing with strings See Structured arrays. Linear Algebra Work in progress. Basic linear algebra to be included here. Simple Array Operations See linalg.py in numpy folder for more. >>> >>> import numpy as np >>> a = np.array([[1.0, 2.0], [3.0, 4.0]]) >>> print(a) [[1. 2.] [3. 4.]] >>> a.transpose() array([[1., 3.], [2., 4.]]) >>> np.linalg.inv(a) array([[-2. , 1. ], [ 1.5, -0.5]]) >>> u = np.eye(2) # unit 2x2 matrix; "eye" represents "I" >>> u array([[1., 0.], [0., 1.]]) >>> j = np.array([[0.0, -1.0], [1.0, 0.0]]) >>> j @ j # matrix product array([[-1., 0.], [ 0., -1.]]) >>> np.trace(u) # trace 2.0 >>> y = np.array([[5.], [7.]]) >>> np.linalg.solve(a, y) array([[-3.], [ 4.]]) >>> np.linalg.eig(j) (array([0.+1.j, 0.-1.j]), array([[0.70710678+0.j , 0.70710678-0.j ], [0. -0.70710678j, 0. +0.70710678j]])) Parameters: square matrix Returns The eigenvalues, each repeated according to its multiplicity. The normalized (unit "length") eigenvectors, such that the column ``v[:,i]`` is the eigenvector corresponding to the eigenvalue ``w[i]`` . Tricks and Tips Here we give a list of short and useful tips. “Automatic” Reshaping To change the dimensions of an array, you can omit one of the sizes which will then be deduced automatically: >>> >>> a = np.arange(30) >>> b = a.reshape((2, -1, 3)) # -1 means "whatever is needed" >>> b.shape (2, 5, 3) >>> b array([[[ 0, 1, 2], [ 3, 4, 5], [ 6, 7, 8], [ 9, 10, 11], [12, 13, 14]], [[15, 16, 17], [18, 19, 20], [21, 22, 23], [24, 25, 26], [27, 28, 29]]]) Vector Stacking How do we construct a 2D array from a list of equally-sized row vectors? In MATLAB this is quite easy: if x and y are two vectors of the same length you only need do m=[x;y]. In NumPy this works via the functions column_stack, dstack, hstack and vstack, depending on the dimension in which the stacking is to be done. For example: >>> >>> x = np.arange(0,10,2) >>> y = np.arange(5) >>> m = np.vstack([x,y]) >>> m array([[0, 2, 4, 6, 8], [0, 1, 2, 3, 4]]) >>> xy = np.hstack([x,y]) >>> xy array([0, 2, 4, 6, 8, 0, 1, 2, 3, 4]) The logic behind those functions in more than two dimensions can be strange. See also NumPy for Matlab users Histograms The NumPy histogram function applied to an array returns a pair of vectors: the histogram of the array and a vector of the bin edges. Beware: matplotlib also has a function to build histograms (called hist, as in Matlab) that differs from the one in NumPy. The main difference is that pylab.hist plots the histogram automatically, while numpy.histogram only generates the data. >>> import numpy as np rg = np.random.default_rng(1) import matplotlib.pyplot as plt # Build a vector of 10000 normal deviates with variance 0.5^2 and mean 2 mu, sigma = 2, 0.5 v = rg.normal(mu,sigma,10000) # Plot a normalized histogram with 50 bins plt.hist(v, bins=50, density=1) # matplotlib version (plot) # Compute the histogram with numpy and then plot it (n, bins) = np.histogram(v, bins=50, density=True) # NumPy version (no plot) plt.plot(.5*(bins[1:]+bins[:-1]), n) ../_images/quickstart-2.png Further reading The Python tutorial NumPy Reference SciPy Tutorial SciPy Lecture Notes A matlab, R, IDL, NumPy/SciPy dictionary © Copyright 2008-2020, The SciPy community. Last updated on Jun 29, 2020. Created using Sphinx 2.4.4.
GroupAYECS765P / BDP 05 Large Scale ClusteringBDP 05: CLUSTERING OF LARGE UNLABELED DATASETS OVERVIEW Real world data is frequently unlabeled and can seem completely random. In these sort of situations, unsupervised learning techniques are a great way to find underlying patterns. This project looks at one such algorithm, KMeans clustering, which searches for boundaries separating groups of points based on their differences in some features. The goal of the project is to implement an unsupervised clustering algorithm using a distributed computing platform. You will implement this algorithm on the stack overflow user base to find different ways the community can be divided, and investigate what causes these groupings. The clustering algorithm must be designed in a way that is appropriate for data intensive parallel computing frameworks. Spark would be the primary choice for this project, but it could also be implemented in Hadoop MapReduce. Algorithm implementations from external libraries such as Spark MLib may not be utilised; the code must be original from the students. However, once the algorithm is completed, a comparison between your own results and that generated by MLlib could be interesting and aid your investigation. Stack Overflow is the main dataset for this project, but alternative datasets can be adopted after consultation with the module organiser. Additionally, different clustering algorithms may be utilised, but this must be discussed and approved y the module organiser. DATASET The project will use the Stack Overflow dataset. This dataset is located in HDFS at /data/stackoverflow The dataset for StackOverflow is a set of files containing Posts, Users, Votes, Comments, PostHistory and PostLinks. Each file contains one XML record per line. For complete schema information: Click here In order to define the clustering use case, you must define what should be the features of each post that will be used to cluster the data. Have a look at the different fields to define your use case. ALGORITHM The project will implement the k-means algorithm for clustering. This algorithm iteratively recomputes the location of k centroids (k is the number of clusters, defined beforehand), that aim to classify the data. Points are labelled to the closest centroid, with each iteration updating the centroids location based on all the points labelled with that value. Spark and Map/Reduce can be utilised for implementing this problem. Spark is recommended for this task, due to its performance benefits in . However, note that the MLib extension of Spark is not allowed to be used as the primary implementation. The group must code its own original implementation of the algorithm. However, it is possible to also use the mllib implementation, in order to evaluate the results from each clustering implementation. Report Contents Brief literature survey on clustering algorithms, including the challenges on implementing them at scale for parallel frameworks. The report should then justify the chosen algorithm (if changed) and the implementation. Definition of the project use case, where the implemented project will be part of the solution. Implementation in MapReduce or Spark of a clustering algorithm(KMeans). Must take into account the potential enormous size of the dataset, and develop sensible code that will scale and efficiently use additional computing nodes. The code will also need to potentially convert the dataset from its storage format to an in-memory representation. Source code should not be included in the report. However, the algorithms should be explained in the report. Results section. Adequate figures and tables should be used to present the results. The effectiveness of the algorithm should also be shown, including performance indications. Not really sure if this can be done for clustering. Critical evaluation of the results should be provided. Experiments demonstrating the technique can successfully group users in the dataset. Representation of the results, and discussion of the findings in a critical manner. ASSESSMENT The project according to the specification has a base difficulty of 85/100. This means that a perfect implementation and report would get a 85. Additional technical features and experimentation would raise the difficulty in order to opt for a full 100/100 mark. Report presentation: 20% Appropriate motivation for the work. Lack of typos/grammar errors, adequate format. Clear flow and style. Related work section including adequate referencing. Technical merit: 50% Completeness of the implementation. [25%] Provided source code. Code is documented. [10%] Design rationale of the code is provided. [10%] Efficient, and appropriate implementation for the chosen platform. [5%] Results/Analysis: 30% Experiments have been carried out on the full dataset. [10%] Adequate plots/tables are provided, with captions. [10%] Results are not only presented but discussed appropriately. [10%] Additional project goals: Implementation of additional functions beyond the base specification can raise the base mark up to 100. A non-exhaustive list of expansion ideas include: Exploration and discussion of hyperparameter tuning (e.g. the number of k groups to cluster the data into) [up to 10 marks] Comparative evaluation of clustering technique with existing implementations (e.g. mllib) [up to 10 marks] Bringing in additional datasets from stackoverflow, such as user badges, to aid in clustering [up to 5 marks] Cluster additional datasets (such as posts) [up to 10 marks] LEAD DEMONSTRATOR For specific queries related to this coursework topic, please liaise with Mr/Ms TBD, who will be the lead demonstrator for this project, as well as with the module organiser. SUBMISSION GUIDELINES The report will have a maximum length of 8 pages, not counting cover page and table of contents. The report must include motivation of the problem, brief literature survey, explanation of the selected technique, implementation details and discussion of the obtained results, and references used in the work. Additionally, the source code must be included as a separate compressed file in the submission.
fazeelkhalid / Graph Real Time ProblemsPoints: 100 Topics: Graphs, topological sort, freedom to decide how to represent data and organize code (while still reading in a graph and performing topological sort) PLAGIARISM/COLLUSION: You should not read any code (solution) that directly solves this problem (e.g. implements DFS, topological sorting or other component needed for the homework). The graph representation provided on the Code page (which you are allowed to use in your solution) and the pseudocode and algorithm discussed in class provide all the information needed. If anything is unclear in the provided materials check with us. You can read materials on how to read from a file, or read a Unix file or how to tokenize a line of code, BUT not in a sample code that deals with graphs or this specific problem. E.g. you can read tutorials about these topics, but not a solution to this problem (or a problem very similar to it). You should not share your code with any classmate or read another classmate's code. Part 1: Main program requirements (100 pts) Given a list of courses and their prerequisites, compute the order in which courses must be taken so that when taking a courses, all its prerequisites have already been taken. All the files that the program would read from are in Unix format (they have the Unix EOL). Provided files: ● Grading Criteria ● cycle0.txt ● data0.txt ● data0_rev.txt ● data1.txt - like data0.txt but the order of the prerequisite courses is modified on line 2. ● slides.txt (graph image) - courses given in such a way that they produce the same graph as in the image. (The last digit in the course number is the same as the vertex corresponding to it in the drawn graph. You can also see this in the vertex-to-course name correspondence in the sample run for this file.) ● run.html● data0_easy.txt - If you cannot handle the above file format, this is an easier file format that you can use, but there will be 15 points lost in this case. More details about this situation are given in Part 3. ● Unix.zip - zipped folder with all data files. ● For your reference: EOL_Mac_Unix_Windows.png - EOL symbols for Unix/Mac/Windows Specifications: 1. You can use structs, macros, typedef. 2. All the code must be in C (not C++, or any other language) 3. Global or static variables are NOT allowed. The exception is using macros to define constants for the size limits (e.g. instead of using 30 for the max course name size). E.g. #define MAX_ARRAY_LENGTH 20 4. You can use static memory (on the frame stack) or dynamic memory. (Do not confuse static memory with static variables.) 5. The program must read from the user a filename. The filename (as given by the user) will include the extension, but NOT the path. E.g.: data0.txt 6. You can open and close the file however many times you want. 7. File format: 1. Unix file. It will have the Unix EOL (end-of-line). 2. Size limits: 1. The file name will be at most 30 characters. 2. A course name will be at most 30 characters 3. A line in the file will be at most 1000 characters. 3. The file ends with an empty new line. 4. Each line (except for the last empty line) has one or more course names. 5. Each course name is a single word (without any spaces). E.g. CSE1310 (with no space between CSE and 1310). 6. There is no empty space at the end of the line. 7. There is exactly one empty space between any two consecutive courses on the same line. (You do not need to worry about having tabs or more than one empty space between 2 courses.) The first course name on each line is the course being described and the following courses are the prerequisites for it. E.g. CSE2315 CSE1310 MATH1426 ENGL13018. The first line describes course CSE2315 and it indicates that CSE2315 has 2 prerequisite courses, namely: CSE1310 and MATH1426. The second line describes course ENG1301 and it indicates that ENG1301 has no prerequisites. 9. You can assume that there is exactly one line for every course, even for those that do not have prerequisites (see ENGL1301 above). Therefore you can count the number of lines in the file to get the total number of courses. 10.The courses are not given in any specific order in the file. 8. You must create a directed graph corresponding to the data in the file. 1. The graph will have as many vertices as different courses listed in the file. 2. You can represent the vertices and edges however you want. 3. You do NOT have to use a graph struct. If you can do all the work with just the 2D table (the adjacency matrix) that is fine. You HAVE TO implement the topological sorting covered in class (as this assignment is on Graphs), but you can organize, represent and store the data however you want. 4. For the edges, you can use either the adjacency matrix representation or the adjacency list. If you use the adjacency list, keep the nodes in the list sorted in increasing order. 5. For each course that has prerequisites, there is an edge, from each prerequisite to that course. Thus the direction of the edge indicates the dependency. The actual edge will be between the vertices in the graph corresponding to these courses. E.g. file data0.txt has: c100 c300 c200 c100 c200 c100 Meaning: c100-----> c200 \ | \ | \ | \ | \ | \ | V V c300(The above drawing is provided here to give a picture of how the data in the file should be interpreted and the graph that represents this data. Your program should *NOT* print this drawing. See the sample run for expected program output.) From this data you should create the correspondence: vertex 0 - c100 vertex 1 - c300 vertex 2 - c200 and you can represent the graph using adjacency matrix (the row and column indexes are provided for convenience): | 0 1 2 ----------------- 0| 0 1 1 1| 0 0 0 2| 0 1 0 e.g. E[0][1] is 1 because vertex 0 corresponds to c100 and vertex 1 corresponds to c300 and c300 has c100 as a prerequisite. Notice that E[1][0] is not 1. If you use the adjacency list representation, then you can print the adjacency list. The list must be sorted in increasing order (e.g. see the list for 0). It should show the corresponding node numbers. E.g. for the above example the adjacency list will be: 0: 1, 2, 1: 2: 1, 6. 7. In order for the output to look the same for everyone, use the correspondence given here: vertex 0 for the course on the first line, vertex 1 for the course on the second line, etc. 1. Print the courses in topological sorted order. This should be done using the DFS (Depth First Search) algorithm that we covered in class and the topological sorting based on DFS discussed in class. There is no topological order if there is a cycle in the graph; in this case print an error message. If in DFV-visit when looking at the (u,v) edge, if the color of v is GRAY then there is a cycle in the graph (and therefore topological sorting is not possible). See the Lecture on topological sorting (You can find the date based on the table on the Scans page and then watch the video from that day. I have also updated the pseudocodein the slides to show that. Refresh the slides and check the date on the first page. If it is 11/26/2020, then you have the most recent version.) 8. (6 points) create and submit 1 test file. It must cover a special case. Indicate what special case you are covering (e.g. no course has any prerequisite). At the top of the file indicate what makes it a special case. Save this file as special.txt. It should be in Unix EOL format. Part 2: Suggestions for improvements (not for grade) 1. CSE Advisors also are mindful and point out to students the "longest path through the degree". That is longest chain of course prerequisites (e.g. CSE1310 ---> CSE1320 --> CSE3318 -->...) as this gives a lower bound on the number of semesters needed until graduation. Can you calculate for each course the LONGEST chain ending with it? E.g. in the above example, there are 2 chains ending with c300 (size 2: just c100-->c300, size 3: c100-->c200-->c300) and you want to show longest path 3 for c300. Can you calculate this number for each course? 2. Allow the user the enter a list of courses taken so far (from the user or from file) and print a list of the courses they can take (they have all the prerequisites for). 3. Ask the user to enter a desired number of courses per semester and suggest a schedule (by semester). Part 3: Implementation suggestions 1. Reading from file: (15 points) For each line in the file, the code can extract the first course and the prerequisites for it. If you cannot process each line in the file correctly, you can use a modified input file that shows on each line, the number of courses, but you would lose the 15 points dedicated to line processing. If your program works with the "easy files", in order to make it easy for the TAs to know which file to provide, please name your C program courses_graph_easy.c. Here is the modification shown for a new example. Instead of c100 c300 c200 c100 c200 the file would have: 1 c1003 c300 c200 c100 1 c200 1. that way the first data on each line is a number that tells how many courses (strings) follow after it on that line. Everything is separated by exactly one space. All the other specifications are the same as for the original file (empty line at the end, no space at the end of any line, length of words, etc). Here is data0_easy.txt Make a direct correspondence between vertex numbers and course names. E.g. the **first** course name on the first line corresponds to vertex 0, the **first** course name on the second line corresponds to vertex 1, etc... 2. 3. The vertex numbers are used to refer to vertices. 4. In order to add an edge in the graph you will need to find the vertex number corresponding to a given course name. E.g. find that c300 corresponds to vertex 1 and c200 corresponds to vertex 2. Now you can set E[2][1] to be 1. (With the adjacency list, add node 1 in the adjacency list for 2 keeping the list sorted.) To help with this, write a function that takes as arguments the list/array of [unique] course names and one course name and returns the index of that course in the list. You can use that index as the vertex number. (This is similar to the indexOf method in Java.) 5. To see all the non-printable characters that may be in a file, find an editor that shows them. E.g. in Notepad++ : open the file, go to View -> Show symbol -> Show all characters. YOU SHOULD TRY THIS! In general, not necessarily for this homework, if you make the text editor show the white spaces, you will know if what you see as 4 empty spaces comes from 4 spaces or from one tab or show other hidden characters. This can help when you tokenize. E.g. here I am using Notepad++ to see the EOL for files saved with Unix/Mac/Windows EOL (see the CR/LF/CRLF at the end of each line): EOL_Mac_Unix_Windows.png How to submit Submit courses_graph.c (or courses_graph_easy.c) and special.txt (the special test case you created) in Canvas . (For courses_graph_easy.c you can submit the "easy" files that you created.)Your program should be named courses_graph.c if it reads from the normal/original files. If instead it reads from the 'easy' files, name it courses_graph_easy.c As stated on the course syllabus, programs must be in C, and must run on omega.uta.edu or the VM. IMPORTANT: Pay close attention to all specifications on this page, including file names and submission format. Even in cases where your answers are correct, points will be taken off liberally for non-compliance with the instructions given on this page (such as wrong file names, wrong compression format for the submitted code, and so on). The reason is that non-compliance with the instructions makes the grading process significantly (and unnecessarily) more time consuming. Contact the instructor or TA if you have any questions
SeanSolberg / CompareTextUnicodeDelphi's System.SysUtils.CompareText function doesn't consider all unicode lowerCase-to-upperCase pairs. This code implements a CompareTextUnicode function that is based on a small set of constant lookup tables from the official data files produced by unicode.org
aniket20june / Time Table Scheduling Using Genetic AlgorithmOne of the most challenging task for every college, school, and company administrator is to create an efficient timetable every year or every semester. The herculean task encompasses a huge amount of time and staff involvement. Moreover, a minute mistake will lead to re-planning of the entire timetable. In the present project, we have tried to resolve this problem to a considerable extent so as to save precious man hours. Switching to a digital way of scheduling a time table will result in the automation of workflow. The algorithm is capable of generating timetables automatically while ensuring that no class overlap with each other. It help align proper schedules and allot faculty by mapping the classes, subjects, and teachers details into the system. We have implemented it using Genetic Algorithms. Genetic Algorithm is a search-based optimization technique based on the principles of Genetics and Natural Selection. It is frequently used to find optimal or near-optimal solutions to difficult problems (NP Hard Problems) that wise would take a lifetime to solve. The nature-inspired algorithms depend on their convergence rate and convergence rate depends on the fitness function and algorithmic parameters. Therefore, considering the above arguments and referring several research papers, we have finalised to go with the Genetic algorithm for given project. However, Population-based algorithms like Genetic Algorithm tend to be time-consuming. GAs have more problems to deal with constraints. Often hybrid approaches outperform specific meta-heuristics. I have implemented a combination of Heuristics and Genetic Algorithms in this project.
hale / SimplefsIn this assessment, you will implement a simple file system that allows you to manage files and directories in a virtual in-memory disk. The file system is to be based on simplified concepts of a File Allocation Table (FAT). Your task is to implement interface functions that allow simple read and write operations on this virtual disk.
ktczakutnyi / ScriptingAndProgramming Applications C867WGU - Scripting and Programming - Applications – C867 COMPETENCIES 4048.2.1 : Introduction to Programming The graduate applies fundamental programming concepts in a specific programming environment. 4048.2.2 : Variables and Data Types The graduate prepares code which declares, initializes, and assigns values to variables of appropriate types as part of the application development process. 4048.2.3 : Control Structures The graduate writes code that implements decision and loop constructs to control the flow of a program. 4048.2.4 : Arrays The graduate creates arrays in order to solve complex problems. 4048.2.5 : Pointers and Memory The graduate applies pointers to solve complex problems. 4048.2.6 : Functions The graduate writes code that creates and manipulates functions and files. 4048.2.7 : Object-Oriented Paradigm The graduate applies object-oriented programming concepts in order to create a basic application. INTRODUCTION Throughout your career in software development, you will develop and maintain new and existing applications. You will be expected to fix issues as well as add new enhancements or migrate existing applications to new platforms or different programming languages. As a software developer, your role will be to create a design of an application based on given business requirements. After the design is completed, you must implement the application based on the design document and provided requirements. In this assessment, you will create a C++ application based on the scenario below. The skills you demonstrate in your completed application will be useful in responding to technical interview questions for future employment. This application may also be added to your portfolio to show to future employers. This project will require an integrated development environment (IDE). You must use either Visual Studio or Xcode for this assessment. Directions for accessing these IDEs can be found in the attached “IDE Instructions.” Your submission should include a zip file with all the necessary code files to compile, support, and run your application. The zip file submission must also keep the project file and folder structure intact for the Visual Studio IDE or Eclipse IDE. SCENARIO You are hired as a contractor to help a university migrate an existing student system to a new platform using C++ language. Since the application already exists, its requirements exist as well, and they are outlined in the next section. You are responsible for implementing the part of the system based on these requirements. A list of data is provided as part of these requirements. This part of the system is responsible for reading and manipulating the provided data. You must write a program containing two classes (i.e., Student and Roster). The program will maintain a current roster of students within a given course. Student data for the program include student ID, first name, last name, email address, age, an array of the number of days to complete each course, and degree program. This information can be found in the “studentData Table” below. The program will read a list of five students and use function calls to manipulate data (see part F4 in the requirements below). While parsing the list of data, the program should create student objects. The entire student list will be stored in one array of students called classRosterArray. Specific data-related output will be directed to the console. studentData Table Student ID First Name Last Name Email Age Days in Course Degree Program A1 John Smith John1989@gm ail.com 20 30, 35, 40 SECURITY A2 Suzan Erickson Erickson_1990@gmailcom 19 50, 30, 40 NETWORK A3 Jack Napoli The_lawyer99yahoo.com 19 20, 40, 33 SOFTWARE A4 Erin Black Erin.black@comcast.net 22 50, 58, 40 SECURITY A5 Your first name Your last name Your valid email address Your age Number of days to complete 3 courses SOFTWARE The data should be input as follows: const string studentData[] = {"A1,John,Smith,John1989@gm ail.com,20,30,35,40,SECURITY", "A2,Suzan,Erickson,Erickson_1990@gmailcom,19,50,30,40,NETWORK", "A3,Jack,Napoli,The_lawyer99yahoo.com,19,20,40,33,SOFTWARE", "A4,Erin,Black,Erin.black@comcast.net,22,50,58,40,SECURITY", "A5,[firstname],[lastname],[emailaddress],[age], [numberofdaystocomplete3courses],SOFTWARE" You may not include third-party libraries. Your submission should include one zip file with all the necessary code files to compile, support, and run your application. You must also provide evidence of the program’s required functionality by taking a screen capture of the console run, saved as an image file. Note: Each file must be an attachment no larger than 30 MB in size. REQUIREMENTS Your submission must be your original work. No more than a combined total of 30% of the submission and no more than a 10% match to any one individual source can be directly quoted or closely paraphrased from sources, even if cited correctly. The originality report that is provided when you submit your task can be used as a guide. You must use the rubric to direct the creation of your submission because it provides detailed criteria that will be used to evaluate your work. Each requirement below may be evaluated by more than one rubric aspect. The rubric aspect titles may contain hyperlinks to relevant portions of the course. Tasks may not be submitted as cloud links, such as links to Google Docs, Google Slides, OneDrive, etc., unless specified in the task requirements. All other submissions must be file types that are uploaded and submitted as attachments (e.g., .docx, .pdf, .ppt). A. Modify the “studentData Table” to include your personal information as the last item. B. Create a C++ project in your integrated development environment (IDE) with the following files: • degree.h • student.h and student.cpp • roster.h and roster.cpp • main.cpp Note: There must be a total of six source code files. C. Define an enumerated data type DegreeProgram for the degree programs containing the data type values SECURITY, NETWORK, and SOFTWARE. Note: This information should be included in the degree.h file. D. For the Student class, do the following: 1. Create the class Student in the files student.h and student.cpp, which includes each of the following variables: • student ID • first name • last name • email address • age • array of number of days to complete each course • degree program 2. Create each of the following functions in the Student class: a. an accessor (i.e., getter) for each instance variable from part D1 b. a mutator (i.e., setter) for each instance variable from part D1 c. All external access and changes to any instance variables of the Student class must be done using accessor and mutator functions. d. constructor using all of the input parameters provided in the table e. print() to print specific student data E. Create a Roster class (roster.cpp) by doing the following: 1. Create an array of pointers, classRosterArray, to hold the data provided in the “studentData Table.” 2. Create a student object for each student in the data table and populate classRosterArray. a. Parse each set of data identified in the “studentData Table.” b. Add each student object to classRosterArray. 3. Define the following functions: a. public void add(string studentID, string firstName, string lastName, string emailAddress, int age, int daysInCourse1, int daysInCourse2, int daysInCourse3, DegreeProgram degreeprogram) that sets the instance variables from part D1 and updates the roster. b. public void remove(string studentID) that removes students from the roster by student ID. If the student ID does not exist, the function prints an error message indicating that the student was not found. c. public void printAll() that prints a complete tab-separated list of student data in the provided format: A1 [tab] First Name: John [tab] Last Name: Smith [tab] Age: 20 [tab]daysInCourse: {35, 40, 55} Degree Program: Security. The printAll() function should loop through all the students in classRosterArray and call the print() function for each student. d. public void printAverageDaysInCourse(string studentID) that correctly prints a student’s average number of days in the three courses. The student is identified by the studentID parameter. e. public void printInvalidEmails() that verifies student email addresses and displays all invalid email addresses to the user. Note: A valid email should include an at sign ('@') and period ('.') and should not include a space (' '). f. public void printByDegreeProgram(DegreeProgram degreeProgram) that prints out student information for a degree program specified by an enumerated type. F. Demonstrate the program’s required functionality by adding a main() function in main.cpp, which will contain the required function calls to achieve the following results: 1. Print out to the screen, via your application, the course title, the programming language used, your WGU student ID, and your name. 2. Create an instance of the Roster class called classRoster. 3. Add each student to classRoster. 4. Convert the following pseudo code to complete the rest of the main() function: classRoster.printAll(); classRoster.printInvalidEmails(); //loop through classRosterArray and for each element: classRoster.printAverageDaysInCourse(/*current_object's student id*/); Note: For the current_object's student id, use an accessor (i.e., getter) for the classRosterArray to access the student id. classRoster.printByDegreeProgram(SOFTWARE); classRoster.remove("A3"); classRoster.printAll(); classRoster.remove("A3"); //expected: the above line should print a message saying such a student with this ID was not found. 5. Implement the destructor to release the memory that was allocated dynamically in Roster. G. Demonstrate professional communication in the content and presentation of your submission.
dsainvi / WGU C950 Data Algorithms 2wgu-c950 Data Structures and Algorithms II - WGU Scenario The Western Governors University Parcel Service (WGUPS) needs to determine the best route and delivery distribution for their Daily Local Deliveries (DLD) because packages are not currently being consistently delivered by their promised deadline. The Salt Lake City DLD route has three trucks, two drivers, and an average of 40 packages to deliver each day; each package has specific criteria and delivery requirements. Your task is to determine the best algorithm, write code, and present a solution where all 40 packages, listed in the attached “WGUPS Package File,” will be delivered on time with the least number of miles added to the combined mileage total of all trucks. The specific delivery locations are shown on the attached “Salt Lake City Downtown Map” and distances to each location are given in the attached “WGUPS Distance Table.” While you work on this assessment, take into consideration the specific delivery time expected for each package and the possibility that the delivery requirements—including the expected delivery time—can be changed by management at any time and at any point along the chosen route. In addition, you should keep in mind that the supervisor should be able to see, at assigned points, the progress of each truck and its packages by any of the variables listed in the “WGUPS Package File,” including what has been delivered and what time the delivery occurred. The intent is to use this solution (program) for this specific location and to use the same program in many cities in each state where WGU has a presence. As such, you will need to include detailed comments, following the industry-standard Python style guide, to make your code easy to read and to justify the decisions you made while writing your program. Assumptions: Each truck can carry a maximum of 16 packages. Trucks travel at an average speed of 18 miles per hour. Trucks have a “infinite amount of gas” with no need to stop. Each driver stays with the same truck as long as that truck is in service. Drivers leave the hub at 8:00 a.m., with the truck loaded, and can return to the hub for packages if needed. The day ends when all 40 packages have been delivered. Delivery time is instantaneous, i.e., no time passes while at a delivery (that time is factored into the average speed of the trucks). There is up to one special note for each package. The wrong delivery address for package #9, Third District Juvenile Court, will be corrected at 10:20 a.m. The correct address is 410 S State St., Salt Lake City, UT 84111. The package ID is unique; there are no collisions. No further assumptions exist or are allowed. Requirements Your submission must be your original work. No more than a combined total of 30% of the submission and no more than a 10% match to any one individual source can be directly quoted or closely paraphrased from sources, even if cited correctly. An originality report is provided when you submit your task that can be used as a guide. You must use the rubric to direct the creation of your submission because it provides detailed criteria that will be used to evaluate your work. Each requirement below may be evaluated by more than one rubric aspect. The rubric aspect titles may contain hyperlinks to relevant portions of the course. Section 1: Programming/Coding A. Identify the algorithm that will be used to create a program to deliver the packages and meets all requirements specified in the scenario. B. Write a core algorithm overview, using the sample given, in which you do the following: Comment using pseudocode to show the logic of the algorithm applied to this software solution. Apply programming models to the scenario. Evaluate space-time complexity using Big O notation throughout the coding and for the entire program. Discuss the ability of your solution to adapt to a changing market and to scalability. Discuss the efficiency and maintainability of the software. Discuss the self-adjusting data structures chosen and their strengths and weaknesses based on the scenario. C. Write an original code to solve and to meet the requirements of lowest mileage usage and having all packages delivered on time. Create a comment within the first line of your code that includes your first name, last name, and student ID. Include comments at each block of code to explain the process and flow of the coding. D. Identify a data structure that can be used with your chosen algorithm to store the package data. Explain how your data structure includes the relationship between the data points you are storing. Note: Do NOT use any existing data structures. You must design, write, implement, and debug all code that you turn in for this assessment. Code downloaded from the internet or acquired from another student or any other source may not be submitted and will result in automatic failure of this assessment. E. Develop a hash table, without using any additional libraries or classes, with an insertion function that takes the following components as input and inserts the components into the hash table: package ID number delivery address delivery deadline delivery city delivery zip code package weight delivery status (e.g., delivered, in route) F. Develop a look-up function that takes the following components as input and returns the corresponding data elements: package ID number delivery address delivery deadline delivery city delivery zip code package weight delivery status (e.g., delivered, in route) G. Provide an interface for the insert and look-up functions to view the status of any package at any time. This function should return all information about each package, including delivery status. Provide screenshots to show package status of all packages at a time between 8:35 a.m. and 9:25 a.m. Provide screenshots to show package status of all packages at a time between 9:35 a.m. and 10:25 a.m. Provide screenshots to show package status of all packages at a time between 12:03 p.m. and 1:12 p.m. H. Run your code and provide screenshots to capture the complete execution of your code. Section 2: Annotations I. Justify your choice of algorithm by doing the following: Describe at least two strengths of the algorithm you chose. Verify that the algorithm you chose meets all the criteria and requirements given in the scenario. Identify two other algorithms that could be used and would have met the criteria and requirements given in the scenario. a. Describe how each algorithm identified in part I3 is different from the algorithm you chose to use in the solution. J. Describe what you would do differently if you did this project again. K. Justify your choice of data structure by doing the following: Verify that the data structure you chose meets all the criteria and requirements given in the scenario. a. Describe the efficiency of the data structure chosen. b. Explain the expected overhead when linking to the next data item. c. Describe the implications of when more package data is added to the system or other changes in scale occur. Identify two other data structures that can meet the same criteria and requirements given in the scenario. a. Describe how each data structure identified in part K2 is different from the data structure you chose to use in the solution. L. Acknowledge sources, using in-text citations and references, for content that is quoted, paraphrased, or summarized. M. Demonstrate professional communication in the content and presentation of your submission.
