CONTRIBUTING.md

Contributing to fastlane

Getting started

Make sure you have bundler installed using gem install bundler

• Open the GitHub page of the fastlanerepository (e.g. https://github.com/fastlane/fastlane)
• Create an issue to discuss your idea/feature/enhancement.
• Click on Fork on the top right
• Then clone your new repo locally git clone https://github.com/[my_user]/fastlane.git
• On your terminal, navigate to the project and run git remote add upstream https://github.com/fastlane/fastlane (or use the git URL if you use private key auth)
• Create your feature branch (git checkout -b my-new-feature).
• Commit your changes (git commit -am 'Add some feature').
• Push to the branch (git push origin my-new-feature).
• Create a new Pull Request.

Before working on something, make sure to have pulled the latest changes. To pull the changes run

git pull master

New Issues

Before submitting a new issue, do the following:

• Verify you're running the latest version by running fastlane -v and compare it with the project page on GitHub.
• Verify you have Xcode tools installed by running xcode-select --install.
• Make sure to read through the README of the project.

When submitting a new issue, please provide the following information:

• The full stack trace and output when running fastlane.
• The command and parameters you used to launch it.
• Your Fastfile and all other configuration files you are using.

By providing this information it's much faster and easier to help you

Helping to Resolve Existing Issues

If you're motivated to help out at a level beyond reporting issues, we really appreciate it! 👍 A good place to start is by reviewing the list of open issues or open PRs for things that need attention. When you find one that you'd like to help with, the countdown repo is the best way to get set up with the source code for all of the fastlane projects. With that, working on the following things are super valuable:

Verifying Bug Reports

Are you able to reproduce this problem on your computer? If so, chime in! If the original issue report is a bit vague, but you have some additional details, please contribute them! If you find a bug report without an example script or configuration, contribute one that can be used to reproduce it.

If you're comfortable diving into the code a bit, see if you can produce a failing test that illustrates the bad behavior in the problematic area of the code! Tests live in the spec/ directory, and are generally named relative to the source code files whose functionality they test. Once you are done, git diff > my_patch.diff can be used to produce a patch file containing the details of your changes, which can be added to the issue.

Testing Proposed Fixes

Another way to help out is to verify submitted pull requests. To do that, you'll need to be able to get the author's proposed changes onto your machine. Start by giving yourself a new branch to work in:

git checkout -b testing_branch

Next, you'll need to tell git where to find this contributor's fastlane fork and branch. Let's say that the contributor's username is JohnSmith and their topic branch is called new_fastlane_action located at https://github.com/JohnSmith/fastlane. You can use the following commands to pull their work:

git remote add JohnSmith https://github.com/JohnSmith/fastlane.git
git pull JohnSmith new_fastlane_action

Once you have their changes locally, there's many things worth checking on:

• Does the change work?
• Are there adequate tests to cover the changes or new functionality? Are the tests clear and testing the right things?
• Is the related documentation updated? New actions get described in docs/Actions.md, for example.
• How does the code look to you? Can you think of a nicer or more performant way to implement part of it?

If you're happy with what you see, leave a comment on the GitHub issue stating your approval. If not, leave a polite suggestion for what you think could be improved and how. The more you can show that you've reviewed the content seriously, the more valuable it will be to the author and other reviewers!

Pull Requests (PRs)

Pull requests are always welcome :simple_smile:

PRs should reference an open GitHub issue (preferably those marked with the help wanted label). Referring to the issue in the description of your PR is required and is really helpful for establishing the context needed for review.

If you're considering contibuting new functionality, please open a new issue explaining the functionality desired first so that we can discuss as a community. We'll add the help wanted label if we believe this to be a meaningful contribution that will benefit other fastlane users and you go ahead with the pull request. 🙌

Pro tip: GitHub will automatically turn references to issue numbers in the form #1234 into a link to the issue/PR with that number within the same repo.

• Adding automated tests that cover your changes and/or new functionality is important!
  • fastlane has a lot of moving parts and receives contributions from many developers. The best way to ensure that your contributions keep working is to ensure that there will be failing tests if something accidentally gets broken.
  • You can run the tests by executing bundle install and then bundle exec rspec.
• Your code editor should indent using spaces with a tab size of 2 spaces.

To submit the changes to the fastlane repo, you have to do the following:

• Squash your commits into one. For example, to squash three commits into one, do the following: $ git rebase -i HEAD~3. In the text editor that comes up, replace the words "pick" with "squash" next to the commits you want to squash. Save and close the editor. For more information, take a look at 7.6 Git Tools - Rewriting History
• Run git push upstream master. If you pushed before squashing, go back and do the previous step, and then run git push upstream master --force
• Open https://github.com/fastlane/fastlane in your browser and click the green "Create Pull Request" button

Why Did My Issue/PR Get Closed?

It's not you, it's us! fastlane and its related tools receive a lot of issues and PRs. In order to effectively work through them and give each the prompt attention it deserves, we need to keep a sharp focus on the work we have outstanding.

One way we do this is by closing issues that we don't feel are immediately actionable. This might mean that we need more information in order to investigate (Have you provided enough information for us to reproduce the problem? The New Issues section has the details!). Or, it might mean that we haven't been able to reproduce it using the provided info. In this case we might close the issue while we wait for others to reproduce the problem and possibly provide some more info that unlocks the mystery.

In any case, a closed issue is not necessarily the end of the story! If more info becomes available after an issue is closed, it can be reopened for further consideration.

One of the best ways we can keep fastlane an approachable, stable, and dependable tool is to be deliberate about how we choose to modify it. If we don't adopt your changes or new feature into fastlane, that doesn't mean it was bad work! It may be that the fastlane philosophy about how to accomplish a particular task doesn't align well with your approach. The best way to make sure that your time is well spent in contributing to fastlane is to start your work on a modification or new feature by opening an issue to discuss the problem or shortcoming with the community. The fastlane maintainers will do our best to give early feedback about whether a particular goal and approach is likely to be something we want to adopt!

Contributing New Actions

Writing a custom action is an easy way to extend the capabilities of fastlane. Actions that make good candidates for inclusion in the fastlane codebase are flexible and apply to many projects, teams, and development setups. Before working to contribute your custom action to fastlane, consider whether it is likely to solve a problem that many developers have. If not, it can still provide value for your fastlane environment! Check out the documentation for creating local action extensions.

Developing

When working on something, directly edit the Ruby files in the project folders. Make sure to switch your text editor to use spaces and indentations should be 2 spaces.

To run the modified version of the tool, run the following in the project directory

./bin/[tool_name]

or install the local copy (might require sudo)

bundle install && rake install

Debugging

I personally use a plain Sublime Text with a terminal. Debugging is pretty easy, just insert the following code to where you want to jump in:

require 'pry'
binding.pry

You then jump into an interactive debugger that allows you to print out variables, call methods and much more. Continue running the original script using control + d

Interacting with the user

You'll see some old code still using puts or Helper.log.info to print out values. From now, please only use the new UI class to interact with the user (both input and output)

UI.message "Neutral message (usually white)"
UI.success "Succesully finished processing (usually green)"
UI.error "Wahaha, what's going on here! (usually red)"
UI.important "Make sure to use Windows (usually yellow)"

UI.header "Inputs" # a big box

name = UI.input("What's your name? ")
if UI.confirm("Are you '#{name}'?")
  UI.success "Oh yeah"
else
  UI.error "Wups, invalid"
end

UI.password("Your password please: ") # password inputs are hidden

###### A "Dropdown" for the user
project = UI.select("Select your project: ", ["Test Project", "Test Workspace"])

UI.success("Okay #{name}, you selected '#{project}'")

###### To run a command use
FastlaneCore::CommandExecutor.execute(command: "ls",
                                    print_all: true,
                                        error: proc do |error_output|
                                          # handle error here
                                        end)

###### or if you just want to receive a simple value use this only if the command doesn't take long
diff = Helper.backticks("git diff")

###### fastlane "crash" because of a user error everything that is caused by the user and is not unexpected
UI.user_error!("You don't have a project in the current directory")

###### an actual crash when something unexpected happened
UI.crash!("Network timeout")

###### a deprecation message
UI.deprecated("The '--key' parameter is deprecated")

The output will look like this

Running tests

In the directory of one project, run the tests using

rake test

This will do a few things:

• Runs the tests (you can run them via rspec too)
• Makes sure no debug code (like pry) is still there
• The --help command works as expected

The tests are executed using fastlane 🚀

To run only a subset of the tests, you can add the now: true keyword to the test

it "raises an exception if it rains", now: true do
  ...
end

and then run these tests only using

rspec -t now

rubocop validation

The fastlane repos use rubocop to validate the code style.

The style validation is automatically done when running rake test.

To automatically fix common code style issues (e.g. wrong spacing), run rubocop -a

Need help?

Please submit an issue on GitHub and provide information about your setup

Code of Conduct

Help us keep fastlane open and inclusive. Please read and follow our Code of Conduct.

Above All, Thanks for Your Contributions

Thank you for reading to the end, and for taking the time to contribute to the project! If you include the 🔑 emoji at the top of the body of your issue or pull request, we'll know that you've given this your full attention and are doing your best to help!

License

This project is licensed under the terms of the MIT license. See the LICENSE file.

This project and all fastlane tools are in no way affiliated with Apple Inc. This project is open source under the MIT license, which means you have full access to the source code and can modify it to fit your own needs. All fastlane tools run on your own computer or server, so your credentials or other sensitive information will never leave your own computer. You are responsible for how you use fastlane tools.