|
1 | | -## How to Contribute |
| 1 | +# How to contribute to AdvantEDGE |
2 | 2 |
|
3 | | -We welcome feedback and improvement suggestions. Please open a Git issue in the repo to report bugs or request enhancements. |
| 3 | +_So you've decided that you would like to contribute to AdvantEDGE project... what next?<br>_ |
4 | 4 |
|
5 | | -At this time, we are not ready to accept pull requests. However, we plan to do so in the future. |
| 5 | +It's great to hear that you have interest in AdvantEDGE & we'd love to accept your bug fix or other contributions; |
| 6 | +there is however few small guidelines that you need to follow before getting started. |
6 | 7 |
|
7 | | -In the meantime, if you have interest in becoming an AdvantEDGE contributor, we would like to hear from you. |
| 8 | +_[... But I just have a question & I don't want to read this whole thing!!!](#if-you-have-questions)_ |
8 | 9 |
|
9 | | -We can be reached at <AdvantEDGE@InterDigital.com> |
| 10 | +There are three main ways of contributing to the project: by reporting an issue, by suggesting an enhancement or by contributing content.<br> As such, we cover these use cases below |
| 11 | +- [Reporting an issue (bug/documentation)](#reporting-issues) |
| 12 | +- [Suggesting an enhancement](#suggesting-enhancements) |
| 13 | +- [Contributing content](#contributing-content) |
| 14 | + - [Contributor License Agreement](#contributor-license-agreement) |
| 15 | + - [Your First Content Contribution](#your-first-content-contribution) |
| 16 | + - [Pull Requests](#pull-request) |
| 17 | + - [But... What can I contribute on?](#what-can-i-contribute-on) |
| 18 | + |
| 19 | +## If You Have Questions |
| 20 | +Please don't open a GitHub Issue to ask a question; you'll get faster result by using the resources below. |
| 21 | + |
| 22 | +#### Resource #1 - AdvantEDGE Wiki |
| 23 | +We put time & efforts keeping the wiki up to date, so we recommend to look there first.<br> |
| 24 | +- Project questions -- [FAQ](https://github.com/InterDigitalInc/AdvantEDGE/wiki/faq) & [Roadmap](https://github.com/InterDigitalInc/AdvantEDGE/wiki/roadmap) |
| 25 | +- Concepts questions -- [Platform concepts](https://github.com/InterDigitalInc/AdvantEDGE/wiki/platform-concepts), [platform APIs](https://github.com/InterDigitalInc/AdvantEDGE/wiki/API-Documentation), [Frontend concepts](https://github.com/InterDigitalInc/AdvantEDGE/wiki/frontend-concepts) |
| 26 | +- Services questions -- [platform APIs](https://github.com/InterDigitalInc/AdvantEDGE/wiki/API-Documentation), [Location service](https://github.com/InterDigitalInc/AdvantEDGE/wiki/location-service), [Application State Transfer service](https://github.com/InterDigitalInc/AdvantEDGE/wiki/state-transfer), [Metrics Engine service](https://github.com/InterDigitalInc/AdvantEDGE/wiki/metrics-engine-service) |
| 27 | +- Setup questions -- [Hardware](https://github.com/InterDigitalInc/AdvantEDGE/wiki/hw-configuration), [Runtime environment](https://github.com/InterDigitalInc/AdvantEDGE/wiki/runtime-environment), [Development environment](https://github.com/InterDigitalInc/AdvantEDGE/wiki/development-environment) |
| 28 | +- Deployment questions -- [meepctl CLI tool](https://github.com/InterDigitalInc/AdvantEDGE/blob/master/docs/meepctl/meepctl.md), [Build](https://github.com/InterDigitalInc/AdvantEDGE/wiki/build-advantedge), [Deploy](https://github.com/InterDigitalInc/AdvantEDGE/wiki/deploy-advantedge), [Upgrade](https://github.com/InterDigitalInc/AdvantEDGE/wiki/upgrade-advantedge), [Test](https://github.com/InterDigitalInc/AdvantEDGE/wiki/test-advantedge) |
| 29 | +- Usage questions -- [GUI](https://github.com/InterDigitalInc/AdvantEDGE/wiki/gui-overview), [basic operation](https://github.com/InterDigitalInc/AdvantEDGE/wiki/basic-operation), [creating a first scenario](https://github.com/InterDigitalInc/AdvantEDGE/wiki/first-scenario), [scenario monitoring](https://github.com/InterDigitalInc/AdvantEDGE/wiki/scenario-monitoring), [using external nodes](https://github.com/InterDigitalInc/AdvantEDGE/wiki/external-nodes), [edge application models](https://github.com/InterDigitalInc/AdvantEDGE/wiki/edge-app-models), [edge application types](https://github.com/InterDigitalInc/AdvantEDGE/wiki/edge-app-types), [pod placement](https://github.com/InterDigitalInc/AdvantEDGE/wiki/pod-placement) |
| 30 | + |
| 31 | +#### Resource #2 - Email us |
| 32 | +Of course - because we cannot document everything - if you still have a question, we can be reached at AdvantEDGE@InterDigital.com |
| 33 | + |
| 34 | +## Reporting issues |
| 35 | +Whether it's a bug found while using the platform or simply a typo noticed while browsing the documentation, we appreciate that you open a GitHub issue ([here](https://github.com/InterDigitalInc/AdvantEDGE/issues)) |
| 36 | + |
| 37 | +#### Bug |
| 38 | +When reporting a bug, try to be as concise & specific as possible so we can reproduce the problem. |
| 39 | + |
| 40 | +A Bug Report template is provided in GitHub to help documenting the problem. |
| 41 | +#### Documentation |
| 42 | +Use the Custom Issue template to provide a link to the page, a copy the problematic text and an indication of what the problem is. |
| 43 | + |
| 44 | +## Suggesting enhancements |
| 45 | +We appreciate feature enhancements and as such, we collect feature ideas via GitHub issues ([here](https://github.com/InterDigitalInc/AdvantEDGE/issues)) |
| 46 | + |
| 47 | +If you are not sure about the proposed enhancement, it's always a good idea to communicate with us (AdvantEDGE@InterDigital.com using subject subject `enhancement`) to discuss the feature beforehand. |
| 48 | + |
| 49 | +Use the Feature Request template provided in GitHub to document the request. |
| 50 | + |
| 51 | +## Contributing content |
| 52 | +Contributing content is more involving than submitting an issue or an enhancement request as it requires a CLA and learning how to operate with the project team. |
| 53 | + |
| 54 | +The following sub-sections cover these aspects. |
| 55 | + |
| 56 | +#### Contributor License Agreement |
| 57 | +In order for us to accept content contributions, a Contributor License Agreement (CLA) is required. |
| 58 | + |
| 59 | +- _[CLA for individual contributor](https://github.com/InterDigitalInc/AdvantEDGE/docs/cla/interdigital-individual-cla-v1.pdf)_ |
| 60 | +- _[CLA for corporate contributors](https://github.com/InterDigitalInc/AdvantEDGE/docs/cla/interdigital-corporate-cla-v1.pdf)_ |
| 61 | + |
| 62 | +Fill-in the requested information and send it to AdvantEDGE@InterDigital.com using subject `CLA` |
| 63 | + |
| 64 | +> Note: it is important to include your GitHub id(s) in the CLA so we know who you are when submitting a pull-request. |
| 65 | +
|
| 66 | +#### Your First Content Contribution |
| 67 | +In order to prepare your contribution, you will need to create your fork of the AdvantEDGE repo. To do so, simply click the Fork button in the [repo](https://github.com/InterDigitalInc/AdvantEDGE) |
| 68 | + |
| 69 | +Your fork is your own copy of the repo where you can modify things without impacting others; your fork's GitHub path should be `https://github.com/<your-gh-username/AdvantEDGE.git` |
| 70 | + |
| 71 | +After creating your fork, you can clone it locally and start making modifications. We also require making modifications on a branch originating from the `develop` branch (preferred) or alternatively the `master` branch. |
| 72 | +``` |
| 73 | +git clone https://github.com/<your-gh-username/AdvantEDGE.git |
| 74 | +git checkout develop |
| 75 | +git checkout -b <your-branch-name> |
| 76 | +``` |
| 77 | + |
| 78 | +During development, keep your commit message concise and precise so we understand what the change is about. |
| 79 | + |
| 80 | +We accept a single contribution per branch, so if you are fixing two bugs - please create two different branches each originating from `develop` & each containing only the necessary changes for the bug they fix. |
| 81 | + |
| 82 | +Finally, for code contributions, we require that you run the linter (e.g. `meepctl lint all`), [Unit Tests](https://github.com/InterDigitalInc/AdvantEDGE/wiki/Test-AdvantEDGE#run-unit-tests) and [Cypress tests](https://github.com/InterDigitalInc/AdvantEDGE/wiki/Test-AdvantEDGE#run-cypress-tests) on your branch. |
| 83 | +> Note: Keep results to include in your pull request. |
| 84 | +
|
| 85 | +#### Pull Request |
| 86 | +With implementation complete and linter/tests passing<br> |
| 87 | +You are ready to make your pull request, [here](https://github.com/InterDigitalInc/AdvantEDGE/pulls). |
| 88 | + |
| 89 | +First, make sure that all necessary code is committed to your branch and that you have pushed your branch back to your fork. |
| 90 | +``` |
| 91 | +git add <your-modified-files> |
| 92 | +git commit -m 'what-has-changed' |
| 93 | +git push |
| 94 | +``` |
| 95 | + |
| 96 | +If unsure, it's a good idea to double check that your branch has been pushed back to the repo using the GitHub browser client. Your fork can be accessed from [here](https://github.com/InterDigitalInc/AdvantEDGE/network/members), your branch should show up in the branch drop down of your fork and your changes should show up once the branch is selected. |
| 97 | + |
| 98 | +In the pull request, indicate the branch containing your changes, the nature of the changes you made, a reference to the related GitHub issue and the test results. |
| 99 | + |
| 100 | +_What to expect next?_<br> |
| 101 | +We do peer reviews of all internal contributions - so as an external contributor you can expect that someone from the core team will review your PR. |
| 102 | + |
| 103 | +This is normal and is part of the process. Be patient as we may be busy addressing other issues - we will eventually get back to you with a status & possibly change requests. Please note that we reserve the right to accept or not a contribution. For internal reasons, from time to time, we may decide not to include your proposition, this has nothing to do with your skills or the value of your contribution. |
| 104 | + |
| 105 | +#### What can I contribute on |
| 106 | +Making first contributions can be intimidating - after all it's often difficult to figure out where to start and learn how to interact with a new team (that's us :) ). This is normal and we are here to help. |
| 107 | + |
| 108 | +We recommend the following approach: |
| 109 | +1. Start small - documentation contributions are an easy way to start as they are simpler to perform. If you used the project before (or not) and find that documentation is confusing / missing - then you may have an opportunity. Alternatively, look for [issues](https://github.com/InterDigitalInc/AdvantEDGE/issues) tagged `documentation` & `good first issue` |
| 110 | +2. Look for the [issues](https://github.com/InterDigitalInc/AdvantEDGE/issues) tagged `good first issue` - as these are simpler and often isolated / self-contained |
| 111 | +3. Once you are accustomed with the project, you can start tackling other larger existing issues. |
| 112 | +4. The holly-grail of contributing would be opening an issue / getting an enhancement request approved and submitting the PR implementing it |
| 113 | + |
| 114 | +Anyhow, when picking an issue, it's always a good idea to comment on the issue to let others know you are looking at it; you can also email us at AdvantEDGE@InterDigital.com |
| 115 | + |
| 116 | +We hope this is helpful - and...<br> |
| 117 | +... looking forward to hear from you! |
0 commit comments