|
| 1 | +# Welcome to python-libjuju contributing guide <!-- omit in toc --> |
| 2 | + |
| 3 | +Thank you for investing your time in contributing to our project! :confetti_ball: :sparkles: |
| 4 | + |
| 5 | +In this guide, you will get an overview of the contribution workflow from opening an issue, |
| 6 | +creating a PR, reviewing, and merging the PR. |
| 7 | + |
| 8 | +Use the table of contents icon <img src="https://github.com/github/docs/raw/41b5e9addc77f16f945ba3429b90c8f130aac9c2/contributing/images/table-of-contents.png" width="25" height="25" /> in the top right corner of this document to get to a specific section of this guide quickly. |
| 9 | + |
| 10 | +## New contributor guide |
| 11 | + |
| 12 | +To get an overview of the project, read the [README](https://github.com/juju/python-libjuju/blob/master/docs/readme.rst). If you need a primer on git, check out [Set up Git](https://docs.github.com/en/get-started/quickstart/set-up-git). |
| 13 | + |
| 14 | +Let's get to some specifics: |
| 15 | + |
| 16 | +<!--- |
| 17 | +- [Finding ways to contribute to open source on GitHub](https://docs.github.com/en/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github) |
| 18 | +- [Set up Git](https://docs.github.com/en/get-started/quickstart/set-up-git) |
| 19 | +- [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) |
| 20 | +- [Collaborating with pull requests](https://docs.github.com/en/github/collaborating-with-pull-requests) |
| 21 | +
|
| 22 | +
|
| 23 | +## Getting started |
| 24 | +
|
| 25 | +To navigate our codebase with confidence, see [the introduction to working in the docs repository](/contributing/working-in-docs-repository.md) :confetti_ball:. For more information on how we write our markdown files, see [the GitHub Markdown reference](contributing/content-markup-reference.md). |
| 26 | +
|
| 27 | +Check to see what [types of contributions](/contributing/types-of-contributions.md) we accept before making changes. Some of them don't even require writing a single line of code :sparkles:. |
| 28 | +
|
| 29 | +--> |
| 30 | + |
| 31 | + |
| 32 | +## Pull Request |
| 33 | + |
| 34 | +Thanks for considering to contribute code to our project! We accept and welcome all kinds of PRs! :tada: |
| 35 | + |
| 36 | +The process is very simple. |
| 37 | +- Fork the project into your account. |
| 38 | +- Clone your fork. |
| 39 | +- Add an upstream remote: `git add upstream git@github.com:juju/python-libjuju.git` |
| 40 | +- Check with `git remote -v`, origin should point to your fork, upstream should point to ours. |
| 41 | +- If your changes are going to be on top of a specific branch (e.g., `2.9`), then fetch and switch to that. |
| 42 | +- `git switch -c your-branch-name` |
| 43 | +- Make your changes, create your commits. |
| 44 | +- `git push -u origin your-branch-name` |
| 45 | + |
| 46 | +And that's it, just follow the link that Git will produce. We kindly ask you to follow our PR template (at least keep the sections there), so it can be faster for us to review and move it forward. |
| 47 | + |
| 48 | +#### What's next |
| 49 | + |
| 50 | +So when you create the PR, a bot might spam some messages there for admins to review the PR. Don't panic, everything's good. Someone from our team needs to push a button to allow for the CI to run. |
| 51 | + |
| 52 | +Some time after we see the tests are passing, someone from our team will review. Whoever reviews |
| 53 | +it might ask for some changes, or some tests to be fixed, etc. Finally, the PR will be approved, and again, |
| 54 | +someone from our team (probably the reviewer) will comment `/merge`, which triggers the Juju bot to start the merging process, which will automagically complete and merge your PR onto the desired branch. :confetti_ball: |
| 55 | + |
| 56 | +#### Some quick notes: |
| 57 | + |
| 58 | +- Don't forget to [link PR any issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) if you are solving any. |
| 59 | +- Enable the checkbox to [allow maintainer edits](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/allowing-changes-to-a-pull-request-branch-created-from-a-fork) so the branch can be updated for a merge. |
| 60 | +- A `/build` comment will trigger a fresh CI run. |
| 61 | +- If you run into any merge issues, checkout this [git tutorial](https://github.com/skills/resolve-merge-conflicts) to help you resolve merge conflicts and other issues. |
| 62 | + |
| 63 | +### Your PR is merged! |
| 64 | + |
| 65 | +Congratulations :tada::tada: The Juju team thanks you :sparkles:. |
| 66 | + |
| 67 | +Now that you are part of the Juju community, hop into our [public Mattermost channel](https://chat.charmhub.io/charmhub/channels/juju) and join the conversation! |
| 68 | + |
| 69 | + |
| 70 | +## Issues |
| 71 | + |
| 72 | +### Create a new issue |
| 73 | + |
| 74 | +If you spot a problem, [search](https://docs.github.com/en/github/searching-for-information-on-github/searching-on-github/searching-issues-and-pull-requests#search-by-the-title-body-or-comments) |
| 75 | +in the [issues page](https://github.com/juju/python-libjuju/issues) to see if an issue already exists about what you're interested in. |
| 76 | +If a related issue doesn't exist, then go ahead and file a [new issue](https://github.com/juju/python-libjuju/issues/new?assignees=&labels=bug&projects=&template=BugReport.yml) |
| 77 | +with our issue template. On the issue form, the most important fields for us are the `Python-libjuju version`, `Juju version`, and |
| 78 | +the `Reproduce/Test` fields to quickly act on it. The `Repdouce/Test` section is especially important, as it makes it much easier to diagnose |
| 79 | +problems and test solutions. Please try to distill your issue and reduce it to a smaller piece of code. |
| 80 | + |
| 81 | +> **_NOTE:_** Please refrain from saying "here's my repository/project/charm that uses |
| 82 | +python-libjuju, get that and run this integration test, and you'll see the issue". |
| 83 | + |
| 84 | +### Submit a feature request |
| 85 | + |
| 86 | +If you're reporting some missing feature, or some functionality that you'd like to have in python-libjuju, feel free to use our |
| 87 | +[feature request form](https://github.com/juju/python-libjuju/issues/new?assignees=&labels=wishlisted&projects=&template=FeatureRequest.yml) |
| 88 | +to report it to us, and we'll make it happen for you. Make sure to fill out the `Code I'd Like to Run` section, so once your feature is implemented we can turn it into a test |
| 89 | +to make sure everything's working exactly as planned. |
| 90 | + |
| 91 | +### Issue Workflow |
| 92 | + |
| 93 | +After an issue is created, it's in the `untriaged` state. Once a week, we walk through every open issue and triage them. |
| 94 | +An issue is triaged when it has the track label (e.g. `2.9`, `3.2`). And once it's assigned to a milestone, that means we're committing to it, i.e., someone's actively working on it. |
| 95 | + |
| 96 | +Scan through our [existing issues](https://github.com/juju/python-libjuju/issues) to find one that interests you. |
| 97 | +You can narrow down the search using `labels` as filters. See our [Labels](https://github.com/juju/python-libjuju/labels) for more information on that. |
| 98 | +As a general rule, we don’t assign issues to anyone. If you find an issue to work on, you are welcome to open a PR with a fix. |
0 commit comments