Contributing¶

Thanks for your interest in contributing to Panda!

As you might have expected, contributions are welcome.

1. Collaboration policy
2. Organization
3. Code of Conduct
4. Key concepts
5. Kanban
6. User stories
7. Epics
8. Milestones
9. Issues workflow
10. Helper labels
11. Status labels
12. Priority labels
13. Type labels
14. GitHub labels
15. Feature requests
16. Bug reports
17. Merge requests
18. Writing Documentation
19. Some hints for newbies
20. Submitting a pull request
21. Coding guidelines
22. Resources

Collaboration policy¶

💁🐼 Contributing to Panda is not different from other projects.

Our collaboration policy communicates how best to work together on this project. Basically, only a few basic rules need to be observed.

• 1. Respect and solidarity come first! Our code of conduct explains community standards that need to be taken into account when interacting with this project.
• 2. Comrade, we need you! There are many ways to contribute; no need to be a technician or developer. Every help and every feedback is appreciated.
• 3. Consider talking before acting! When contributing to this project we first discuss the proposed changes in the team via new issue, email, or any other method.
• 4. Issues can be everything! No matter whether bugs, tasks, or ideas to be discussed – the issue tracker is the best place to add things that need to be improved or solved in this project.

In case you are contributing to this project for the first time, it would be nice if you could briefly introduce yourself, telling us about your interest in the project and related experiences.

Working on your first Pull Request? You can learn how from this free series How to Contribute to an Open Source Project on GitHub.

❤️ Thanks a lot for your interest in contributing to Panda! ❤️

Organization¶

Visit Team panda! for details. We use ZenHub Workspaces.

See Working with ZenHub if you are new to the world of Scrum and Kanban.

See Track team Velocity sprint-over-sprint for infos about velocity charts.

This project is organized as follows:

Roadmap > Milestones > Epics > Issues

An issue can be a feature request or enhancement formulated as a user story, a bug report, or a proposed patch submitted as a pull request.

Not only code contributions but also help with docs, e.g. translations, proofreading, etc. is highly appreciated.

We accept pull requests for bug fixes and features, and welcome discussing the approach in an issue.

We would also love to hear about ideas for new features as issues.

Contributions to this project are released under the AGPLv3 license.

Please note that this project adheres to a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Code of Conduct¶

Our Code of Conduct has been adapted from the Contributor Covenant, version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct/.

The Contributor Covenant was created by Coraline Ada Ehmke in 2014 and is released under the CC BY 4.0 license.

For answers to common questions about their Code of Conduct, please see https://www.contributor-covenant.org/faq.

Key concepts¶

Our development workflow consists of several basic Agile principles.

In accordance with the Agile Manifesto we value:

• ***Individuals and interactions** over processes and tools*
• ***Working software** over comprehensive documentation*
• ***Customer collaboration** over contract negotiation*
• ***Responding to change** over following a plan*

Team members should be more or less familiar with these concepts:

• Kanban system
• DevOps toolchain
• CI/CD
• Application lifecycle management
• User stories
• Issues
• Bug reports
• Feature requests
• Epics
• Semantic Versioning (MAJOR.MINOR.PATCH)
• Release cycles
• Milestones

Kanban¶

Project management for Panda development is based on a methodology called Kanban.

Originating in the automotive industry, Kanban has been introduced to the IT industries by David J. Anderson over ten years ago.

The initial Kanban project management system has been pioneered in Japan, being developed by Taiichi Ohno as part of the Toyota Production System.

TPS or Toyotism is a production model and management theory that followed the paradigm of Fordism-Taylorism in the post-war period.

Taylorism and Fordism emerged from the efficiency movement in the decade between 1905 and 1915 and remained the predominant mode of production worldwide until the late 1970s.

The Toyota system – with Kanban at its heart – has been developed between 1948 and 1975, revolutionizing the modern mode of production. It became predominant in the era of post-fordism and neoliberal globalization in the 1980's.

Both paradigms – Fordism-Taylorism and Toyotism – aim to maximize efficiency and output while identifying and eliminating waste in all areas of the economy and society.

Toyota's Taiichi Ohno identifies seven wastes in a typical manufacturing workflow, called Muda.

• Overproduction (largest waste)
• Waiting
• Transportation
• Overprocessing
• Inventory
• Motion
• Defects (broken products)
• Underutilized workforce

Based on the wording of Lean Production and Lean Manufacturing coming – from the automotive industry as well –, we sometimes speak of Lean Methods, Lean Management, Lean IT, Lean Development, Lean Services, Lean Maintenance, etc.

At the end of the twentieth century terms like Just-in-Time production (JIT), Short-cycle manufacturing (SCM), or Continuous-flow manufacturing (CFM) have been in use for similar philosophies.

The continuous improvement process - called Kaizen in Japanese - is an essential part of Kanban.

The main idea behind Kanban is to minimize the lead time or workload between releases (see value chain and supply chain) by keeping the number of work in progress (i.e. tasks processed in parallel) low – and to maximize the number of deployments and releases by using CI/CD automation.

The progress is visualized and prioritized on the Kanban board. Each task or user story is represented by a post-it note on a whiteboard.

The Kanban board is split into various columns representing the status of an issue.

• To do means this issue still needs to be worked on. (This can be a new issue or an older issue coming from the backlog.)
• In progress means somebody is already working on the issue. (This can be analyzing, bug fixing, reviewing, or even rejecting.)
• Done means just that. (Somebody took care and created a PR. Someone else did a review and closed the issue.)

User stories¶

Each major task is broken down into a manageable number of smaller tasks.

The smallest entity is an issue – representing a simple user story.

The user story informs other team members or external contributors about the who, what, and why of an issue making use of signal words, keywords and tags.

As administrator I want to have permission to lock or delete standard user accounts.

From this example all contributors should recognize on the spot that

1. The user type is the admin role.
2. The task is the implementation of permission handling.
3. The goal is locking or deleting an existing user.

Try to clarify your request or user story with code examples and sketches such as

• screenshots with manual markings
• mockups (see: mock object)
• scribbles or doodles

Epics¶

Epics are like chapters. Depending on the estimated workload a task can be divided into several sub-tasks. Such big issues are called epics.

Think of an epic as a large user story (like our role-based security example) represented by an issue with the label epic.

This issue or ticket should include a checklist of linked sub-tasks needed to be completed in order to close the epic.

Each issue or epic in turn needs to be linked to a Kanban project.

According to the nature of the issue and the team that will be working on it, this can be

• api: 👽 Issues or PRs related to GraphGL, ONIX, B2B and external API changes
• core: 🐼 Issues or PRs related to Panda Core, Composer, Bedrock or ClassicPress
• design: 🎨 Issues or PRs related to pandastic theme or assets like SCSS and SVGs
• documentation: 📝 Improvements or additions to documentation. This label is for issues and PRs/MRs that only require a documentation change, to differentiate from those coupled with a feature change. This label can be used for epics, issues, and merge requests related to product documentation.
• environments: 👷 Control CI/CD workflows and pipelines. This label is for issues about environments and deployments.
• infra: 🔧 Issues or PRs related to infrastructure like Docker or development scripts
• php: ⚙️ Issues or pull requests that update PHP code.
• rbac: 🛂 Issues or PRs related to authorization, roles and permissions

Milestones¶

A milestone defines the chunk of work planned for the next minor release. It shows the big picture of what needs to be done to bring our project to the next level.

Think of milestones as anchors or markers for our major goals.

The two-weeks lasting period between milestones is called a sprint or an iteration.

Iterations start on a Tuesday and finish on a Monday.

Each iteration should be a milestone in GitHub in the format MAJOR.MINOR, like 1.4.

Issues workflow¶

It is considered best practice to search the issue tracker for similar entries before submitting a new issue. There is a good chance that someone else already had the same issue, change request or feature proposal.

Showing support with an emoji at the respective comment is appreciated as much as taking part in the discussion.

Tags or labels like bug, security or rbac (for role-based access control) will help organizing and sorting our issues. They can be set at issue creation, as part of a review, or when working on it.

Currently we use over thirty different labels. This number may grow in the future.

Feature requests¶

To request a change to the way Panda works, opening an issue is enough. The team will regularly discuss new feature requests, and consider the top three suggestions.

Bug reports¶

Everybody knows: Bugs are unfortunate, but a reality in software. As we cannot fix what we do not know about, we kindly ask everybody to report generously.

If you are not sure whether something is a bug or not, feel free to file a bug anyway.

If you believe that reporting your bug publicly poses a security risk to our users, please contact us via email.

Merge requests¶

Our team loves merge requests from everyone. By participating in this project, readers agree to abide by our code of conduct.

NB: It should be noted that merge requests here are equivalent to what others may call pull requests.

Merge requests are a place to propose changes made to a project, and to discuss those changes with others.

Interested parties can even contribute by directly pushing commits to a proper development branch if they want to.

Merge requests are the preferred method for code review and change management in this project. By this an assigned team member can be asked to merge two branches – development and feature branch.

After a review and discussion process the git merge command successfully will be the final action that is requested of the assignee, therefore the name of this approach.

Merge requests lead to higher-quality code by involvement of as many team members as possible, both checking code quality and assuring compliance with coding standards.

1. It must be ensured that any install or build dependencies are removed before the end of the layer when performing a build.
2. The README.md file and the respective documentation must be updated with details of relevant changes. This includes new environment variables, exposed ports, useful file locations and container parameters.
3. The version number in any sample files, in the environment variables, in the README.md file, etc. must be increased to the new version that this merge request would represent. The version scheme used is SemVer.

4. A Merge request may be completed with the git merge command by the contributors themselves – given the permission, a so-called Sign-off, from at least one team member. By signing off contributors or the respective team member indicate that the original contributor accepts the Developer's Certificate of Origin, thus certifying that no portion of the patch has been taken from a third pary without permission, and that the commit can be published and legally redistributed under the license terms of this project.

   $ git commit --signoff
   

   Signed-off-by: Pablo Hörtner <redtux@pm.me>
   

5. In case such a permission is missing for any reason contributors may request another team member to review the patch and merge it for them.

Writing Documentation¶

Documentation improvements are very welcome. Contributions can be made directly here or at Panda Docs.

Some hints for newbies¶

• Check existing issues to verify that the bug or feature request has not already been submitted.
• Open an issue if things are not working as expected.
• Open an issue to propose a significant change.
• Open a pull request to fix a bug.
• Open a pull request to fix documentation about a command.
• Open a pull request if a member of the Panda team has given the ok after discussion in an issue.
• Add installation instructions specifically for your OS/package manager to install.

Submitting a pull request¶

1. Fork and clone the repository
2. Create a new branch: git checkout -b my-branch-name
3. Make your change, add tests, and ensure tests pass
4. Submit a pull request: gh pr create --web

Coding guidelines¶

• Please follow the PSR-2 Coding Style Guide.
• Ensure that the current tests pass.
• If you add new features or code, include the respective tests where relevant.
• Send a coherent commit history, making sure each individual commit in your pull request is meaningful.
• You may need to rebase to avoid merge conflicts.
• If you are changing or adding to the behaviour or public API, you may need to update the docs.
• Please remember that Panda follows the SemVer standard for versioning.

Resources¶

• How to Contribute to Open Source
• Using Pull Requests
• GitHub Help