First-time contributors#

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

For students and learners#

Important

We do not offer training, guidance, or mentoring to students or learners on GitHub. Don't ask for it. The Plone organization may delete comments, lock conversations, or block GitHub users who ignore this.

If you are a student or learner of Plone, you probably are not a contributor. See the next section, Expectations of first-time contributors, to determine whether you are in fact a contributor.

For free support, training, guidance, or mentoring, you should work through some trainings, use the Plone Community Forum, participate in an event, and not use GitHub.

Expectations of first-time contributors#

As a first-time contributor to Plone on GitHub, we expect that you have:

Warning

As a first-time contributor on GitHub, your expectations should align with ours, else you might feel disappointment or frustration.

Plone has a very large and complex code base. It takes a significant amount of time to learn how to develop Plone.

If you want to quickly pad your résumé, satisfy a "contribute to open source" school assignment, or get recognition for participating in events such as Hacktoberfest, then Plone may not be the open source software project for you. Such motivation behind these contributions usually results in poor quality breaking code, and drains limited volunteer time to triage.

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.

  3. Don't create and close multiple pull requests for the same issue. GitHub should not be used as a place to test your contribution. It makes it impossible for reviewers to provide feedback to your contribution in one place. It also sends notifications to hundreds of developers, informing them that you have not read this guide, and annoying many of them. You should instead learn how to Work with GitHub issues and run tests and code quality checks locally.

  4. Don't ask if an issue is open. Instead you can determine whether an issue is open by doing your own research using the following tips.

    • Start Plone or its specific package, follow the steps to attempt to reproduce the issue, and see if it still exists.

    • Check the issue's status indicator for a green label of Open.

    • Look for linked open pull requests in the issue's history.

    • Search open pull requests for the issue. Sometimes contributors fail to link their pull request to an open issue.

    • Review unreleased change log entries in the package's news directory. Each pull request must have a change log entry, and these entries end up here when pull requests are merged and closed.

    • Search release notes to see whether the issue has been resolved. On rare occasions, contributors forget to close the original issue.

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 business 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. You can filter GitHub issues by labels. 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.

    Issues labeled 42 lvl: moderate, 43 lvl: complex, or 03 type: feature (plip) are not suitable for first-timers because of their complexity. Issues with these labels may take weeks to complete.

  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#

As a member of the Plone Contributors Team, you do not have write access to push commits to GitHub repositories under the Plone organization. You can push commits to your fork. Thus a typical workflow will be circular in nature. You will pull code from the upstream Plone repository, push your work from your local clone to your remote fork, then make a pull request from your fork to the upstream Plone repository.

Plone git workflow

Plone git workflow

  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.

In the following command examples, we will use main as the default branch, although master may still be in use for some repositories.

Always start by checking out the default branch then update the default branch.

git checkout main
git pull

Then create a new branch from the default branch, tracking the upstream Plone repository, 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 switch -c my-branch-name -t upstream/main

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. Do not depend upon our continuous integration and GitHub Workflows to run these checks for you. Every commit you push sends an email notification to repository subscribers. This will save you, members, 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 -u origin my-branch-name

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

    • Make both your title and description descriptive. Reviewers look at many pull requests, and need to quickly understand the context. A lazily written phrase such as "Fixes bug" is meaningless.

    • Include "Fixes #ISSUE-NUMBER" in the description. This enables automatic closing of the related issue when the pull request is merged. This also creates a hyperlink to the original issue for easy reference.

      See also

      Linking a pull request to an issue using a keyword

  3. Request a review. Identify who you should ask by either checking the history of the files you edit, or viewing the project's list of contributors for an active member. If you have write access to the repository, request a review from other team members. If you do not have write access, instead add a comment and mention a few active contributors of the project, tagging them with @username. You can find them by either checking the files' history via git blame or visiting the project's Contributors page on GitHub.

  4. Members who subscribe to the repository will receive a notification and review your request. They will usually provide feedback within a week.

Update your pull request from your fork#

Often another pull request will get merged before yours, and your pull request will fall behind the main branch. To keep your pull request current, you can issue the following git commands, assuming you have already checked out the branch for the pull request that you want to update. These commands will only work if you have Set up your environment as mentioned above.

# Assume `main` is the main branch.
git fetch upstream
git merge upstream/main  # You might need to resolve conflicts here.
git push

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