leogermani 12:56 pm on June 4, 2020  

Welcome post to the Code Reference

Hi! Welcome to the WCEU 2020 Contributor dayContributor Day Contributor Days are standalone days, frequently held before or after WordCamps but they can also happen at any time. They are events where people get together to work on various areas of https://make.wordpress.org/ There are many teams that people can participate in, each with a different focus. https://2017.us.wordcamp.org/contributor-day/ https://make.wordpress.org/support/handbook/getting-started/getting-started-at-a-contributor-day/.!

So you’re interested in contribute to the Developer documentation? That’s great! We definitely need help!

This post is a quick introduction on how to contribute to the code reference.

First, read this

If you haven’t done it already, check this page so you can the basics of what we do and get started setting up the basic accounts and tools you need: New Contributos on a Contributor day. This page is a MUST READ.

Now, let’s do it!

Open these tabs

These are two links you will always have opened in your browser:

  • Editing Code Reference – This page has the general guidelines to editing the articles and also have detailed instructions on how to redirect articles from Codex to DevHub
  • Migration spreadsheet – This is the spreadsheet where we keep track of all the functions, classes and hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. that need to be migrated. Here’s where you will pick stuff to work on most of the time.

The migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. process

After choosing a function/hook to work on, we will:

  • check if all the information that is in codex is already in devHub
  • If it’s not, add it to DevHub (at this point you will need access to edit devHub pages)
  • Once everything is in place, we can retire the page on codex and redirect it to devHub

The structure of an article

The documentation for code reference, including hooks, are separated in 3 parts:

#1 Inline Docs

This is the hook/function name, the parameters it accepts, the value it returns, etc. This is parsed from the source code. If we spot errors there (or room for improvement) we have to open a tracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. ticket and submit a patch to the WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. (instructions here https://make.wordpress.org/docs/handbook/code-reference/inline-documentation/#how-to-open-new-document-ticket)

#2 More Information (aka Explanation)

This is a room for some additional text to explain what the hook is for and how to use it. This is edited via the DevHub admin panel. Many hooks/functions don’t need this, because they are very simple and the explanation in the Inline docs are enough. We can have one or few examples here if it’s really necessary (often it is), but we are favoring leaving the examples for the User Contributed Notes.

For more complex functions, this section might be broken in several subsections. Feel free to add headings (H3 or lower) to the the content and it will be automatically added to the Table of Contents of the article.

This section is not mandatory. Some very simple functions/hooks might not need this. Just the inline docs and an example in the comments might be enough.

#3 User Contributed Notes (aka comments)

this is a space open for contributions. Anyone can leave a comment with examples. There are some of us in the team who moderate it so we only get good examples there. When moving from codex to devHub, we often move the examples to this section, just adding a note that this was migrated from codex)

Editing

  1. Choose the article you want to work on
  2. Put your name on the spreadsheet so people know you’re working on it
  3. Check the page on codex and on DevHub and make sure all the information in codex is present in the new page on DevHub. See the previous section on the article structure to decide where each part of the content should be moved to
  4. Once you think it’s ready ask a friend to review it
  5. Looks good? Redirect the article in codex, so it points to the new DevHub page

Things to keep in mind:

  • There must be at least one example, either in the More Information section or in the Comments
  • You don’t have to copy everything as it is. You can improve things if you like
  • Codex is not the source of absolute truth. There are outdated information and even wrong information. Please check!
  • When writing code examples, please follow the Coding Standards

Nice, where should I start?

I’ve selected some easy and advanced hooks/functions here to help you get started:

https://docs.google.com/spreadsheets/d/1MOs9x-wdD6QnFY8VoNOnWwazGPkhuwZy_jCK_5fBYds/edit#gid=0

But feel free to navigate the Migration Code Reference spreadsheet and choose anything that is not migrated yet!