First-time contributors#

This chapter provides guidance to first-time contributors to Plone and all its projects and repositories under the Plone GitHub organization.

It is assumed that the first-time contributor has already installed Plone on their development machine, has a GitHub account, and has basic knowledge of using git and GitHub.

Requirements#

All first-time contributors to Plone must follow the contributing requirements described in Contributing to Plone.

For Plone Google Summer of Code (GSoC) applicants, you must also follow both our and its program guidelines.

Make contributions through GitHub#

Contributions to Plone are managed through git repositories on GitHub. This section first discusses what not to do, then how to work effectively with a project on GitHub.

Things not to do#

The following is a list of the most frequent mistakes made by first-time contributors. Learn from their mistakes, and don't commit them yourself.

  1. Never ask to be assigned to an issue. Instead you may post a comment to claim it, if no one else has claimed it (see Avoid duplicate effort). For example, "I am working on this issue in pull request #123." You do not need to ask to be assigned to, or to work on, an open issue. As in any open source software project, you can start work on open issues at your convenience. Privileged team members may ignore or delete comments asking to be assigned to an issue.

  2. Avoid duplicate effort. Don't work on issues that have already been claimed or worked on, unless such effort has been abandoned by the author. GitHub's interface provides links to related issues and pull requests, and who is assigned to an issue. Pull requests will be reviewed in the order received. Duplicate pull requests may be ignored and closed without comment by the privileged GitHub teams.

Plone Contributors Team#

The Plone GitHub organization uses GitHub Teams to grant groups of GitHub users appropriate access to its repositories. New users, including GSoC applicants, are assigned to the Contributors Team within a few days after they have signed and returned the Plone Contributor Agreement. New contributors should wait for confirmation that they have been added to this team before creating a pull request to a Plone project.

mr-roboto on GitHub#

mr-roboto enforces the requirement of a signed Plone Contributor Agreement from a new contributor, and being assigned to a Plone team on GitHub.

New contributors to Plone who submit a pull request and do not wait for confirmation that they have been added to the Contributors team will be subjected to persistent nagging from mr-roboto. mr-roboto will not respond to you if you @ it. Core developers may ignore your contribution because you did not follow these instructions. Please don't be "that person".

Work with GitHub issues#

  1. Find issues that you want to work on. Working on documentation or on issues labeled with either 33 needs: docs or 41 lvl: easy are the two best ways for first-time contributors to contribute. This is because first-timers have a fresh perspective that might be overlooked by old-timers.

  2. Discuss whether you should perform any work. First see Avoid duplicate effort. Next, any discussion method listed below is acceptable, and they are listed in the order of most likely to get a response.

    • Search for open issues in the issue trackers of Plone projects on GitHub, and comment on them.

    • If an issue does not already exist for what you want to work on, then create a new issue in its issue tracker. Use a descriptive title and description, include steps to reproduce the issue, and screenshots or videos that demonstrate the issue.

    • Discuss during sprints, conferences, trainings, and other Plone events.

    • Discuss on the Plone Community Forum.

    • Discuss in the Plone chat on Discord.

  3. Clarify the scope of work that needs to be done. Sometimes the issue description is blank or lacks clarity, the requirements have changed since it was created, or work has been completed in a pull request but the issue was not closed. Ask for clarification, whether it is still relevant, or whether it should be closed.

After you have satisfied the above steps and have clear direction on how to proceed, then you can begin work on the issue.

Set up your environment#

  1. Start by forking the project's repository to your account through the GitHub interface.

  2. Clone your forked repository.

  3. Configure git to sync your fork with the upstream repository.

Write code#

Once you have your environment set up, then you can follow standard best practices for working with git.

Always start by checking out the default branch, usually main or master, then update the default branch.

git checkout main
git pull

Then create a new branch from the default branch, and check it out to work on it. We recommend using a branch name that includes the issue number and is descriptive of what it resolves.

git checkout -b branch_name

Now you can edit your code without affecting the default branch.

Note

The Plone organization is aware of the racially insensitive terms that exist in our projects. We are working to correct this mistake. We ask for your patience as we work through complex automated workflows that need to be updated.

Test and code quality#

Follow the project's testing and code quality policies. Most projects have a test suite and code quality checkers and formatters. We strongly recommend that you run the project's test suite and code quality checks locally before proceeding. This will save you and reviewers a lot of time and frustration.

A bug fix or new feature should have a test that ensures that it works as intended.

Create a pull request from your fork#

Once you have completed, tested, and linted your code, and created a Change log entry, then you can follow the standard practice for making a pull request.

  1. Commit and push your changes to your fork.

    git add <files>
git commit -m "My commit message"
git push

  2. Visit your fork of the Plone repository on GitHub, and create a pull request against the development branch.

    • Make your title and description descriptive. Don't be lazy with "Fixes bug" or other useless drivel.

    • To automatically close the original issue when your pull request is merged, include "Closes #issue_number" in your description. This also creates a hyperlink to the original issue for easy reference.

  3. Request a review from other team members.

  4. Members who subscribe to the repository will receive a notification and review your request.

Todo

Provide instructions when the contributor needs to update their pull request with changes from the default branch. Members of Contributors do not have the button "Update branch" to easily do this, and must use git foo to manage the situation.

Welcome to the Plone community, and thank you for contributing!