Skip to content

Contributing

Jump to bottom
Jaime Pastor edited this page Jun 5, 2018 · 4 revisions

Contributing to adidas projects

These are the general contribution guidelines for the adidas projects. In this document there are several sections explaining how to contribute with code, how to report either an issue or a new feature, how to prepare a pull request, the code review process, etc.

adidas wants you to be part of the public code.

Code of Conduct

adidas is a company that thinks that having an open mind is important, so, we want to be open with the source code too.

Our code of conduct reflect our values, so we want you to be part of this having into account some important points which will make our collaboration easier.

  • Respect: we are working to share our work with you, so, we want to grow with you, let us discuss to come to an agreement with good behavior and manners. Personal attacks should never happen, we are, all together, working to improve the open source. Be careful with the words that you choose, the communication is the most important thing. We do not accept: jokes, sexually explicit or violent content, insults, etc.
  • Open mind: there are people from a lot of countries working in adidas, so the adidas culture promotes diversity, let us do the same regarding the public code. Diversity is welcome, it does not matter the nationality, race, ethnicity, gender, age, social class, religion and so on to be a contributor, we are sure that unity creates strength.
  • Understanding: despite the fact that English is the core language for open source projects, it is not the mother language for a lot of people. Let us use appropriate sentences and explain the ideas as better as you can. Try to understand other points of view, if you disagree, start a discussion and try to come to an agreement which satisfies the parties involved.

Let us all make a better open source community.

Opening issues and requesting features

The issues panel is one of the ways to contribute to a project. Opening an issue is the way to communicate that you have found a bug, malfunction or you just want to request a new feature.

Before opening an issue, check the list of open issues in order to avoid duplications. If there is nothing similar open or already discussed and closed, you can report it by creating a new issue to the proper adidas GitHub repository, it does not matter the type of issue to be reported: bug or feature.

There are several templates available in every repository to choose the most suitable one for the purpose of the issue. You have to choose the appropriate one and fill the issue information:

  • Bugs:
    • Issue description.
    • Version affected.
    • How to reproduce it (steps, device, dependencies, etc.).
  • Features:
    • Proposal, detailed description and benefits to have it.

Both types of issues have to be discussed before being accepted. However, if you are able to implement the changes, please, open a pull request, we will appreciate that.

Contributing

In this section we are going to provide you the general guidelines to contribute to any adidas project. However, any project has its own CONTRIBUTING.md file with specific guidelines, check them too.

Development process

These are the steps which to follow to contribute to any project:

  1. Fork the repository in your personal account
  2. Create a new branch in your forked repository using the branch marked as default of the project.
  3. Setup the project following the project installation steps in the README.md file.
  4. Run the available tasks locally to ensure that everything works in your local environment.
  5. Perform the source code modifications:
    • Update the tests (do not forget to test corner cases) and run them.
    • Test the modifications with a real case (use the debugger).
    • Run the lint tasks (if available) and check the coding guidelines.
  6. Update the CHANGELOG.md file with your changes:
    • Pay attentition to describe the breaking changes and deprecated code.
  7. Prepare the pull request.
  8. adidas will do the code review and start a discussion to fix and clarify the issues.

Preparing a pull request

Remember to search for a similar issue in the issues and in the pull requests list, which is important in order to avoid duplicate effort for everyone.

Once the changes are done, everything has been tested, and all the processes have been run in the local environment, the pull request can be opened. Follow the next steps:

  1. Commit the changes following the adidas naming conventions.
    • You can perform several commits, but try not to mix changes with different purpose in the same commit.
    • Learn about changing a commit message.
  2. Push your branch to your forked repository.
  3. Open a pull request to the branch marked as default of the adidas repository.
    • If your branch is not updated with the main repository branch, updated it and test your changes again.
    • We recommend to review the changes by yourself once again, to be sure that everything is correct and all the related changes have been pushed.
    • If you have created a snippet of code to test the changes, it is a good idea to share it in the pull request description, just showing the code or sharing a link of an online tool, such as repl.it, which can be used for most of the languages, or choose the one that you like most.
  4. Add commits to your branch if something has to be updated or fixed according to the review comments.
    • Never delete your branch until the pull request is merged nor modify its history using force push unless you are allowed to do that in the selected repository.
  5. When the pull request is approved it will be merged by adidas team.

Take into account the next points:

  • The code review is a basic part of the development process and it is useful not only to check the code but to discuss about the functionality and other aspects.
  • The code review can last more than the expected time, be patient. However, if adidas does not take charge of it, consider to ping the owners using their GitHub names in a new comment.
  • The merge stragegy is chosen individually for each repository (normal merge, squash, rebase, etc.), check the CONTRIBUTING.md provided to know how to proceed with your commits.

When the pull request is merged, you can delete your local branch and pull the changes merged on the main adidas repository.

Finally, thank you for your contribution!

Coding guidelines

adidas is following the most accepted coding guidelines for the community, so, it will not be difficult for you to use them and to write a good code.

Most of the projects have automated tasks to check the coding guidelines using static code linting tools. It is mandatory to run these tasks to ensure that the code is compliant. Check the README.md file to know how to run these tasks.

The coding guidelines depend on the language used in the project, however, some projects can set different rules if it is necessary for any reason, check the CONTRIBUTING.md file.

The coding style guidelines for the different languages can be found at the coding style guidelines page.

Naming conventions

In order to have an uniform history, good commit descriptions, and descriptive branch names, it is important to follow the naming conventions.

  • Branch name: the branch name consists of two parts, the issue type and the issue description.
    • Issue type: bugfix or feature.
    • Description: kebab-case description.
    • Examples:
      • feature/add-filter-for-sorting-data
      • bugfix/fix-sorting-algorithm-when-no-data
  • Commit message: the message of each commit is mandatory and it has to be as much as descriptive as possible. Check this guide to know how to write a commit message).
    • Title:
      • It starts with a verb in infinitive form which is the main action performed: Add, Fix, Remove, etc.
      • It has to show the name of the entity which has been modified.
      • It is mandatory and it should not exceed 40 characters length.
    • Body (optional):
      • If the title is not enough to describe the changes, use the body.
      • Wrap it at 72 characters.
      • Description of the breaking changes in a deep way.

The issue title and description should also follow the next rules: - Title: it is the summary of the issue or of the changes of the pull request, try to be brief but meaningful. - Description: fill out the template provided according to the issue type, and describe the issue following the guide (opening issues and requesting features).

Reverting a commit

Depending on the commit strategy of the project, if there is no other option to revert a commit that perform a new one, instead of removing it and perform a force push, it has to begin with REVERT: , followed by the title of the reverted commit.

The body shows the hash of the reverted commit to be able to check the changes and history: Reverted commit <hash>..

Learn more about undo changes.

Thank you for your contribution!

adidas

Clone this wiki locally